@whanext/core 0.7.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 Todas as mudanças relevantes do projeto serão registradas neste arquivo.
 
+## 0.10.0
+
+### Adicionado
+
+- `CommandContext`, uma interação enriquecida que continua compatível com o modelo `Message` legado.
+- `ctx.reply()`, `ctx.defer()`, `ctx.edit()`, `ctx.react()`, `ctx.unreact()`, `ctx.delete()` e respostas com exclusão programada.
+- `option.string`, `number`, `boolean`, `enum`, `user` e `duration`, com inferência de tipos, obrigatoriedade e validações.
+- `defineCommandGroup()` e `defineSubcommand()` para comandos como `&grupo abrir` e `&grupo fechar`.
+- Guards reutilizáveis para grupo, privado, admin, bot admin e regras customizadas.
+- Middleware global e por comando, além de hooks `beforeExecute`, `afterExecute` e `onError`.
+- Cooldown por usuário, chat, usuário+chat ou global, com limpeza automática de entradas expiradas.
+- Controle de concorrência com estratégias `parallel`, `reject`, `queue` e `replace`.
+- `app.commands`, catálogo consultável, categorias, busca e help gerado por metadados.
+- Localizações de nome, aliases e descrição sem duplicar definições.
+- Códigos de erro `COMMAND_COOLDOWN` e `COMMAND_BUSY`.
+
+### Compatibilidade
+
+- `app.router()` continua retornando o mesmo router disponível em `app.commands`.
+- `onlyGroup`, `onlyPrivate`, `onlyAdmin` e `botMustBeAdmin` continuam suportados.
+- Comandos legados com `execute(message, args)` continuam funcionando sem alteração.
+- `loadCommands()` agora também reconhece grupos de comandos.
+
+## 0.9.0
+
+### Alterado
+
+- Baileys atualizado de `7.0.0-rc13` para `7.0.0-rc14`.
+- O provider agora fornece `cachedGroupMetadata` ao Baileys, evitando consultas redundantes ao WhatsApp no fan-out de mensagens em grupos.
+- O cache interno usado pelo envio possui TTL, LRU limitado, deduplicação de buscas concorrentes e proteção contra a reinserção de resultados invalidados durante uma busca.
+- `MemoryCache` agora promove corretamente chaves sobrescritas na ordem LRU.
+
+### Adicionado
+
+- `MemoryCache.stats()` para observar hits, misses, sets, evictions e expirations.
+- `MemoryCache.prune()` para remover entradas expiradas de forma explícita.
+
+### Compatibilidade
+
+- Nenhuma alteração é necessária nos comandos ou na API pública existente.
+- Sessões criadas pela v0.8 continuam compatíveis; o auth state multifile do Baileys 7 já persiste as chaves de LID, device list e TC token exigidas pela migração.
+
+## 0.8.0
+
+### Adicionado
+
+- `app.media.sticker(chatId, { sticker })` para enviar stickers WebP estáticos ou animados a partir de bytes, URL ou arquivo local.
+
 ## 0.7.0
 
 ### Adicionado

package/README.md

@@ -290,6 +290,10 @@ await app.media.audio(chatId, {
   voice: true,
 });
 
+await app.media.sticker(chatId, {
+  sticker: { path: './sticker.webp' },
+});
+
 const downloaded = await app.media.download(message);
 
 await writeFile(`./downloads/${downloaded.fileName ?? message.id}`, downloaded.data);
@@ -297,7 +301,7 @@ await writeFile(`./downloads/${downloaded.fileName ?? message.id}`, downloaded.d
 
 `download()` aceita a `Message` recebida ou a sua `MessageKey` e devolve o buffer junto dos metadados normalizados. A mídia deve ser baixada enquanto a mensagem ainda está no cache da instância; o provider tenta renovar a URL de mídia automaticamente quando necessário.
 
-Texto, imagem e vídeo aceitam `User` diretamente em `mentions`.
+Stickers aceitam `Uint8Array`, URL ou caminho local e devem estar em WebP, inclusive para animações. Texto, imagem e vídeo aceitam `User` diretamente em `mentions`.
 
 ## Grupos e membros
 
@@ -397,6 +401,137 @@ const app = await create({
 
 ## Comandos
 
+O sistema moderno usa um contexto semelhante às interactions do Discord. `ctx` contém a mensagem normalizada, usuário, chat, grupo, services, options, sinal de cancelamento e helpers de resposta.
+
+```ts
+import {
+  defineCommand,
+  guards,
+  option,
+} from '@whanext/core';
+
+app.commands.command(
+  defineCommand({
+    name: 'ban',
+    aliases: ['banir'],
+    description: 'Remove um membro do grupo.',
+    category: 'moderação',
+
+    guards: [
+      guards.group(),
+      guards.userAdmin(),
+      guards.botAdmin(),
+    ],
+
+    options: {
+      user: option.user({
+        description: 'Usuário que será removido.',
+        required: true,
+      }),
+      reason: option.string({
+        description: 'Motivo da remoção.',
+        rest: true,
+      }),
+    },
+
+    cooldown: {
+      durationMs: 5_000,
+      scope: 'user-chat',
+    },
+
+    concurrency: {
+      scope: 'chat',
+      max: 1,
+      strategy: 'queue',
+    },
+
+    async execute(ctx) {
+      const user = ctx.options.user('user');
+      const reason = ctx.options.string('reason') ?? 'Não informado';
+      const deferred = await ctx.defer('⏳ _Processando banimento..._');
+      const result = await ctx.members.remove(ctx.chatId, user);
+
+      await deferred.edit(
+        result.changed
+          ? `🔨 *Usuário banido*\n\n${user.mention} foi removido.\n• *Motivo:* ${reason}`
+          : `⚠️ O usuário não está mais no grupo.`,
+      );
+    },
+  }),
+);
+```
+
+### Subcomandos
+
+```ts
+import {
+  defineCommandGroup,
+  defineSubcommand,
+  guards,
+} from '@whanext/core';
+
+app.commands.command(defineCommandGroup({
+  name: 'grupo',
+  aliases: ['group'],
+  description: 'Gerencia o grupo.',
+  category: 'grupos',
+  guards: [guards.group(), guards.userAdmin(), guards.botAdmin()],
+
+  subcommands: [
+    defineSubcommand({
+      name: 'abrir',
+      aliases: ['open'],
+      description: 'Abre o grupo.',
+      async execute(ctx) {
+        await ctx.groups.open(ctx.chatId);
+        await ctx.reply('🔓 *Grupo aberto*');
+      },
+    }),
+    defineSubcommand({
+      name: 'fechar',
+      aliases: ['close'],
+      description: 'Fecha o grupo.',
+      async execute(ctx) {
+        await ctx.groups.close(ctx.chatId);
+        await ctx.reply('🔒 *Grupo fechado*');
+      },
+    }),
+  ],
+}));
+```
+
+Isso aceita `&grupo abrir`, `&group open`, `&grupo fechar` e `&group close` sem duplicar lógica.
+
+### Middleware e erros
+
+```ts
+app.commands.use(async (ctx, next) => {
+  const startedAt = performance.now();
+  await next();
+  app.logger.debug('Command completed', {
+    command: ctx.command.path.join(' '),
+    durationMs: performance.now() - startedAt,
+  });
+});
+
+app.commands.onError(async (ctx, error) => {
+  if (error.code === 'COMMAND_COOLDOWN') {
+    await ctx.reply('⏱️ Aguarde um pouco antes de usar novamente.');
+    return;
+  }
+
+  await ctx.reply('⚠️ *Não foi possível concluir*');
+});
+```
+
+`app.commands.catalog()`, `categories()`, `find()`, `has()` e `values()` expõem a coleção registrada. `app.commands.help(ctx, { category: 'moderação' })` gera a ajuda usando descrição, usage, opções e visibilidade dos comandos.
+
+Detalhes completos estão em [Comandos modernos](./docs/commands-v0.10.md).
+
+### API legada
+
+Comandos existentes continuam válidos:
+
 ```ts
 app.router().command(
   defineCommand({
@@ -520,12 +655,33 @@ const app = await create({
 
 O cache padrão vive na instância do app, usa LRU limitado e elimina entradas expiradas durante as leituras. Consultas simultâneas dos mesmos metadados são agrupadas em uma única chamada ao WhatsApp. Eventos e mutações de grupo invalidam automaticamente entradas relacionadas.
 
+Os mesmos metadados também alimentam internamente o `cachedGroupMetadata` do Baileys. Em grupos já aquecidos, isso remove a consulta de metadados do caminho de envio; mensagens continuam aguardando somente criptografia, upload quando houver mídia e confirmação da rede.
+
+Para observar um `MemoryCache` criado diretamente:
+
+```ts
+import { MemoryCache } from '@whanext/core';
+
+const cache = new MemoryCache({ maxEntries: 5_000 });
+
+console.log(cache.stats());
+cache.prune();
+```
+
+`stats()` informa `size`, `maxEntries`, `hits`, `misses`, `sets`, `evictions` e `expirations`.
+
+Para uma única instância, o cache padrão é suficiente mesmo com muitos grupos, desde que `memoryMaxEntries` seja dimensionado. Em várias instâncias/processos, use um `CacheStore` distribuído para o cache público; cada conexão mantém ainda um L1 local limitado para o caminho criptográfico do Baileys. Não compartilhe uma mesma sessão ativa entre processos.
+
 O cache interno de mensagens mantém até 1.000 mensagens por padrão para replies, reenvios do provider e downloads de mídia. Ajuste quando necessário:
 
 ```ts
 const app = await create({ messageCacheSize: 2_000 });
 ```
 
+Não há delay artificial no envio. Presença é enviada diretamente e previews de alta qualidade permanecem desativados no provider; mídias ainda dependem do tempo de leitura, criptografia e upload ao WhatsApp.
+
+Para limites, dimensionamento e decisões de produção, consulte [Desempenho e escala](./docs/performance-and-scale.md).
+
 ## Presença
 
 ```ts
@@ -567,7 +723,7 @@ Todos os erros públicos usam `WhaNextError` e códigos estáveis. O logger regi
 | Domínio | Responsabilidade |
 | --- | --- |
 | `app.message` | Envio, reply, edição, exclusão, texto e reações |
-| `app.media` | Envio e download de mídia |
+| `app.media` | Envio, download e stickers |
 | `app.group` | Estado, convite, pin e metadados |
 | `app.member` | Remoção, promoção e rebaixamento |
 | `app.user` | Criação e resolução de usuários |

package/SECURITY.md

@@ -4,7 +4,7 @@
 
 | Versão | Suporte |
 | --- | --- |
-| 0.7.x | Sim |
+| 0.8.x | Sim |
 | anteriores | Não |
 
 ## Reportando uma vulnerabilidade

package/dist/index.d.ts

@@ -142,34 +142,10 @@ interface AudioContent {
     mimetype?: string;
     voice?: boolean;
 }
-type MessageContent = TextContent | ImageContent | VideoContent | AudioContent;
-
-interface CommandDefinition {
-    name: string;
-    description: string;
-    aliases?: readonly string[];
-    onlyGroup?: boolean;
-    onlyPrivate?: boolean;
-    onlyAdmin?: boolean;
-    botMustBeAdmin?: boolean;
-    execute(message: Message, args: ArgsParser): void | Promise<void>;
+interface StickerContent {
+    sticker: MediaSource;
 }
-declare function defineCommand<const Command extends CommandDefinition>(command: Command): Command;
-declare function defineCommands<const Commands extends readonly CommandDefinition[]>(...commands: Commands): Commands;
-
-type WhaNextErrorCode = 'AUTH_INVALID_PHONE' | 'AUTH_EXPIRED' | 'CONNECTION_CLOSED' | 'CONNECTION_FAILED' | 'GROUP_NOT_FOUND' | 'MEMBER_NOT_FOUND' | 'BOT_NOT_ADMIN' | 'MESSAGE_NOT_FOUND' | 'MEDIA_NOT_AVAILABLE' | 'MUTE_DISABLED' | 'STORAGE_ERROR' | 'ARGUMENT_MISSING' | 'ARGUMENT_INVALID' | 'COMMAND_NOT_ALLOWED' | 'COMMAND_LOAD_FAILED' | 'PROVIDER_ERROR' | 'UNKNOWN_ERROR';
-interface WhaNextErrorOptions {
-    cause?: unknown;
-    context?: Readonly<Record<string, unknown>>;
-    recoverable?: boolean;
-}
-declare class WhaNextError extends Error {
-    readonly code: WhaNextErrorCode;
-    readonly context: Readonly<Record<string, unknown>>;
-    readonly recoverable: boolean;
-    constructor(code: WhaNextErrorCode, message: string, options?: WhaNextErrorOptions);
-}
-declare function toWhaNextError(error: unknown, context?: Readonly<Record<string, unknown>>): WhaNextError;
+type MessageContent = TextContent | ImageContent | VideoContent | AudioContent | StickerContent;
 
 type GroupAccess = 'open' | 'closed';
 type GroupRole = 'member' | 'admin' | 'owner';
@@ -283,47 +259,75 @@ declare class GroupService {
     invalidate(groupId: string): Promise<void>;
 }
 
-interface RouterOptions {
-    prefix?: string;
-    onError?: (error: WhaNextError, message: Message) => void | Promise<void>;
-}
-declare class CommandRouter {
+declare class UserService {
     #private;
-    constructor(group: GroupService, options?: RouterOptions);
-    command(definition: CommandDefinition): this;
-    dispatch(message: Message): Promise<boolean>;
+    constructor(group: GroupService);
+    resolve(message: Message, args: ArgsParser): Promise<User>;
+    from(identity: string): User;
 }
 
-type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
-type LogFormat = 'pretty' | 'json';
-type LogContext = Readonly<Record<string, unknown>>;
-interface LogEntry {
-    timestamp: string;
-    level: Exclude<LogLevel, 'silent'>;
-    scope: string;
-    message: string;
-    context: LogContext;
+interface BaseOption<TKind extends string> {
+    kind: TKind;
+    description: string;
+    required?: boolean;
 }
-type LogWriter = (entry: LogEntry) => unknown;
-interface LoggerOptions {
-    level?: LogLevel;
-    format?: LogFormat;
-    writer?: LogWriter;
-    scope?: string;
-    redact?: readonly string[];
+interface StringOption extends BaseOption<'string'> {
+    rest?: boolean;
+    minLength?: number;
+    maxLength?: number;
 }
-type LoggerConfig = LogLevel | LoggerOptions;
-declare class Logger {
+interface NumberOption extends BaseOption<'number'> {
+    min?: number;
+    max?: number;
+}
+interface BooleanOption extends BaseOption<'boolean'> {
+}
+interface UserOption extends BaseOption<'user'> {
+}
+interface DurationOption extends BaseOption<'duration'> {
+}
+interface EnumOption<Values extends readonly string[] = readonly string[]> extends BaseOption<'enum'> {
+    values: Values;
+}
+type CommandOptionDefinition = StringOption | NumberOption | BooleanOption | UserOption | DurationOption | EnumOption;
+type CommandOptionSchema = Readonly<Record<string, CommandOptionDefinition>>;
+type RawOptionValue<Definition extends CommandOptionDefinition> = Definition extends StringOption ? string : Definition extends NumberOption ? number : Definition extends BooleanOption ? boolean : Definition extends UserOption ? User : Definition extends DurationOption ? number | undefined : Definition extends EnumOption<infer Values> ? Values[number] : never;
+type CommandOptionValue<Definition extends CommandOptionDefinition> = Definition['required'] extends true ? RawOptionValue<Definition> : RawOptionValue<Definition> | undefined;
+type CommandOptionValues<Schema extends CommandOptionSchema> = {
+    readonly [Name in keyof Schema]: CommandOptionValue<Schema[Name]>;
+};
+declare const option: {
+    string<const Definition extends Omit<StringOption, "kind">>(definition: Definition): {
+        kind: "string";
+    } & Definition;
+    number<const Definition extends Omit<NumberOption, "kind">>(definition: Definition): {
+        kind: "number";
+    } & Definition;
+    boolean<const Definition extends Omit<BooleanOption, "kind">>(definition: Definition): {
+        kind: "boolean";
+    } & Definition;
+    user<const Definition extends Omit<UserOption, "kind">>(definition: Definition): {
+        kind: "user";
+    } & Definition;
+    duration<const Definition extends Omit<DurationOption, "kind">>(definition: Definition): {
+        kind: "duration";
+    } & Definition;
+    enum<const Values extends readonly string[], const Definition extends Omit<EnumOption<Values>, "kind" | "values">>(values: Values, definition: Definition): {
+        kind: "enum";
+        values: Values;
+    } & Definition;
+};
+declare class ParsedCommandOptions<Schema extends CommandOptionSchema = CommandOptionSchema> {
     #private;
-    constructor(config?: LoggerConfig);
-    get level(): LogLevel;
-    setLevel(level: LogLevel): this;
-    isEnabled(level: Exclude<LogLevel, 'silent'>): boolean;
-    child(scope: string): Logger;
-    debug(message: string, context?: LogContext): void;
-    info(message: string, context?: LogContext): void;
-    warn(message: string, context?: LogContext): void;
-    error(message: string, context?: LogContext): void;
+    constructor(values: CommandOptionValues<Schema>);
+    get<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    string<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    number<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    boolean<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    user<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    duration<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    enum<Name extends keyof Schema>(name: Name): CommandOptionValue<Schema[Name]>;
+    toJSON(): CommandOptionValues<Schema>;
 }
 
 interface StoredMute {
@@ -410,6 +414,7 @@ declare class MediaService {
     image(chatId: string, content: ImageContent): Promise<SentMessage>;
     video(chatId: string, content: VideoContent): Promise<SentMessage>;
     audio(chatId: string, content: AudioContent): Promise<SentMessage>;
+    sticker(chatId: string, content: StickerContent): Promise<SentMessage>;
     download(message: Message | MessageKey): Promise<DownloadedMedia>;
 }
 
@@ -433,11 +438,215 @@ declare class MessageService {
     text(chatId: string, text: string, mentions?: MentionTarget[]): Promise<SentMessage>;
 }
 
-declare class UserService {
+interface CommandRuntimeServices {
+    messages: MessageService;
+    media: MediaService;
+    groups: GroupService;
+    members: MemberService;
+    chats: ChatService;
+    users: UserService;
+    mute: MuteService;
+}
+interface CommandChatContext {
+    id: string;
+    isGroup: boolean;
+}
+interface CommandGroupContext {
+    id: string;
+    metadata(refresh?: boolean): ReturnType<GroupService['metadata']>;
+    isUserAdmin(): Promise<boolean>;
+    isBotAdmin(): Promise<boolean>;
+}
+interface ReplyOptions {
+    deleteAfterMs?: number;
+}
+interface CommandContext<Schema extends CommandOptionSchema = CommandOptionSchema> extends Message {
+    readonly message: Message;
+    readonly user: User;
+    readonly chat: CommandChatContext;
+    readonly group: CommandGroupContext | undefined;
+    readonly command: RegisteredCommand;
+    readonly options: ParsedCommandOptions<Schema>;
+    readonly args: ArgsParser;
+    readonly locale: string | undefined;
+    readonly signal: AbortSignal;
+    readonly client: CommandRuntimeServices;
+    readonly messages: MessageService;
+    readonly mediaService: MediaService;
+    readonly groups: GroupService;
+    readonly members: MemberService;
+    readonly chats: ChatService;
+    readonly users: UserService;
+    readonly muteService: MuteService;
+    reply(content: string | MessageContent, options?: ReplyOptions): Promise<SentMessage>;
+    defer(content?: string | MessageContent): Promise<DeferredReply>;
+    edit(content: string): Promise<SentMessage>;
+    react(emoji: string): Promise<SentMessage>;
+    unreact(): Promise<SentMessage>;
+    delete(): Promise<void>;
+    deleteReply(options?: ReplyOptions): Promise<void>;
+}
+declare class DeferredReply {
     #private;
-    constructor(group: GroupService);
-    resolve(message: Message, args: ArgsParser): Promise<User>;
-    from(identity: string): User;
+    constructor(messages: MessageService, message: SentMessage, onEdit: (message: SentMessage) => void);
+    edit(content: string): Promise<SentMessage>;
+    delete(): Promise<void>;
+}
+
+type WhaNextErrorCode = 'AUTH_INVALID_PHONE' | 'AUTH_EXPIRED' | 'CONNECTION_CLOSED' | 'CONNECTION_FAILED' | 'GROUP_NOT_FOUND' | 'MEMBER_NOT_FOUND' | 'BOT_NOT_ADMIN' | 'MESSAGE_NOT_FOUND' | 'MEDIA_NOT_AVAILABLE' | 'MUTE_DISABLED' | 'STORAGE_ERROR' | 'ARGUMENT_MISSING' | 'ARGUMENT_INVALID' | 'COMMAND_NOT_ALLOWED' | 'COMMAND_COOLDOWN' | 'COMMAND_BUSY' | 'COMMAND_LOAD_FAILED' | 'PROVIDER_ERROR' | 'UNKNOWN_ERROR';
+interface WhaNextErrorOptions {
+    cause?: unknown;
+    context?: Readonly<Record<string, unknown>>;
+    recoverable?: boolean;
+}
+declare class WhaNextError extends Error {
+    readonly code: WhaNextErrorCode;
+    readonly context: Readonly<Record<string, unknown>>;
+    readonly recoverable: boolean;
+    constructor(code: WhaNextErrorCode, message: string, options?: WhaNextErrorOptions);
+}
+declare function toWhaNextError(error: unknown, context?: Readonly<Record<string, unknown>>): WhaNextError;
+
+interface GuardResult {
+    allowed: boolean;
+    code?: WhaNextErrorCode;
+    message?: string;
+}
+type CommandGuard = (context: CommandContext) => boolean | void | GuardResult | Promise<boolean | void | GuardResult>;
+declare const guards: {
+    group(): CommandGuard;
+    private(): CommandGuard;
+    userAdmin(): CommandGuard;
+    botAdmin(): CommandGuard;
+    botEnabled(check: (context: CommandContext) => boolean | Promise<boolean>): CommandGuard;
+    custom(guard: CommandGuard): CommandGuard;
+};
+
+type CommandScope = 'global' | 'user' | 'chat' | 'user-chat' | 'user-group';
+type ConcurrencyStrategy = 'parallel' | 'reject' | 'queue' | 'replace';
+interface CommandCooldown {
+    durationMs: number;
+    scope?: CommandScope;
+}
+interface CommandConcurrency {
+    max?: number;
+    scope?: CommandScope;
+    strategy?: ConcurrencyStrategy;
+}
+interface CommandLocalization {
+    name?: string;
+    aliases?: readonly string[];
+    description?: string;
+}
+type CommandMiddleware = (context: CommandContext, next: () => Promise<void>) => void | Promise<void>;
+interface CommandHooks {
+    beforeExecute?: (context: CommandContext) => void | Promise<void>;
+    afterExecute?: (context: CommandContext) => void | Promise<void>;
+    onError?: (context: CommandContext, error: Error) => void | Promise<void>;
+}
+interface CommandMetadata {
+    name: string;
+    description: string;
+    aliases?: readonly string[];
+    category?: string;
+    usage?: string;
+    examples?: readonly string[];
+    hidden?: boolean;
+    localizations?: Readonly<Record<string, CommandLocalization>>;
+    guards?: readonly CommandGuard[];
+    middleware?: readonly CommandMiddleware[];
+    cooldown?: CommandCooldown;
+    concurrency?: CommandConcurrency;
+    hooks?: CommandHooks;
+    onlyGroup?: boolean;
+    onlyPrivate?: boolean;
+    onlyAdmin?: boolean;
+    botMustBeAdmin?: boolean;
+}
+interface ExecutableCommandDefinition<Schema extends CommandOptionSchema = CommandOptionSchema> extends CommandMetadata {
+    options?: Schema;
+    execute(context: CommandContext<Schema>, args: ArgsParser): void | Promise<void>;
+}
+interface CommandGroupDefinition extends CommandMetadata {
+    subcommands: readonly CommandDefinition[];
+}
+type CommandDefinition<Schema extends CommandOptionSchema = CommandOptionSchema> = ExecutableCommandDefinition<Schema> | CommandGroupDefinition;
+interface RegisteredCommand {
+    definition: ExecutableCommandDefinition;
+    root: CommandDefinition;
+    path: readonly string[];
+    aliases: readonly string[];
+    category: string;
+}
+declare function defineCommand<const Schema extends CommandOptionSchema = CommandOptionSchema>(command: ExecutableCommandDefinition<Schema>): ExecutableCommandDefinition<Schema>;
+declare function defineSubcommand<const Schema extends CommandOptionSchema = CommandOptionSchema>(command: ExecutableCommandDefinition<Schema>): ExecutableCommandDefinition<Schema>;
+declare function defineCommandGroup<const Group extends CommandGroupDefinition>(group: Group): Group;
+declare function defineCommands<const Commands extends readonly CommandDefinition[]>(...commands: Commands): Commands;
+declare function isCommandGroup(definition: CommandDefinition): definition is CommandGroupDefinition;
+
+interface RouterOptions {
+    prefix?: string;
+    onError?: (error: WhaNextError, message: Message) => void | Promise<void>;
+    onCommandError?: CommandErrorHandler;
+    beforeExecute?: (context: CommandContext) => void | Promise<void>;
+    afterExecute?: (context: CommandContext) => void | Promise<void>;
+}
+interface CommandCatalogOptions {
+    category?: string;
+    includeHidden?: boolean;
+}
+interface CommandHelpOptions extends CommandCatalogOptions {
+    title?: string;
+}
+type CommandErrorHandler = (context: CommandContext, error: WhaNextError) => void | Promise<void>;
+declare class CommandRouter {
+    #private;
+    constructor(services: CommandRuntimeServices, options?: RouterOptions);
+    constructor(group: GroupService, options?: RouterOptions);
+    get prefix(): string;
+    get size(): number;
+    command(definition: CommandDefinition): this;
+    use(middleware: CommandMiddleware): this;
+    onError(handler: CommandErrorHandler): () => void;
+    catalog(options?: CommandCatalogOptions): readonly RegisteredCommand[];
+    categories(): readonly string[];
+    has(path: string): boolean;
+    values(): readonly RegisteredCommand[];
+    find(path: string): RegisteredCommand | undefined;
+    help(context: CommandContext, options?: CommandHelpOptions): Promise<SentMessage>;
+    dispatch(message: Message): Promise<boolean>;
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+type LogFormat = 'pretty' | 'json';
+type LogContext = Readonly<Record<string, unknown>>;
+interface LogEntry {
+    timestamp: string;
+    level: Exclude<LogLevel, 'silent'>;
+    scope: string;
+    message: string;
+    context: LogContext;
+}
+type LogWriter = (entry: LogEntry) => unknown;
+interface LoggerOptions {
+    level?: LogLevel;
+    format?: LogFormat;
+    writer?: LogWriter;
+    scope?: string;
+    redact?: readonly string[];
+}
+type LoggerConfig = LogLevel | LoggerOptions;
+declare class Logger {
+    #private;
+    constructor(config?: LoggerConfig);
+    get level(): LogLevel;
+    setLevel(level: LogLevel): this;
+    isEnabled(level: Exclude<LogLevel, 'silent'>): boolean;
+    child(scope: string): Logger;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext): void;
 }
 
 interface AppEvents {
@@ -480,6 +689,7 @@ declare class WhaNextApp {
     readonly user: UserService;
     readonly mute: MuteService;
     readonly logger: Logger;
+    readonly commands: CommandRouter;
     constructor(provider: WhatsAppProvider, options?: WhaNextAppOptions, logger?: Logger);
     get state(): ConnectionUpdate['state'];
     get isReady(): boolean;
@@ -517,6 +727,15 @@ interface CreateOptions {
 }
 declare function create(options?: CreateOptions): Promise<WhaNextApp>;
 
+interface MemoryCacheStats {
+    size: number;
+    maxEntries: number;
+    hits: number;
+    misses: number;
+    sets: number;
+    evictions: number;
+    expirations: number;
+}
 declare class MemoryCache implements CacheStore {
     #private;
     constructor(options?: {
@@ -526,6 +745,8 @@ declare class MemoryCache implements CacheStore {
     set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
     delete(key: string): Promise<void>;
     clear(): Promise<void>;
+    prune(now?: number): number;
+    stats(): Readonly<MemoryCacheStats>;
 }
 
 interface CommandRegistrar {
@@ -556,4 +777,4 @@ declare class SqliteMuteStore implements MuteStore {
     close(): void;
 }
 
-export { type AddMuteOptions, type AddMuteResult, type AppEvents, type AppHealth, type AppHealthStatus, ArgsParser, type AudioContent, Browser, type CacheOptions, type CacheStore, type CallEvent, type CallStatus, type ChangeResult, type CommandDefinition, type CommandRegistrar, CommandRouter, type ConnectionState, type ConnectionUpdate, type CreateOptions, type DownloadedMedia, type GroupAccess, type GroupAddressingMode, type GroupParticipant, type GroupParticipantAction, type GroupParticipantsChanged, type GroupRole, type GroupSnapshot, type ImageContent, type InviteResult, type LoadCommandsOptions, type LoadCommandsResult, type LoadedCommand, type LogContext, type LogEntry, type LogFormat, type LogLevel, type LogWriter, Logger, type LoggerConfig, type LoggerOptions, type LoginOptions, type MediaKind, type MediaSource, type MemberActionState, MemoryCache, type MentionTarget, type Message, type MessageContent, type MessageKey, type MessageMedia, type MuteChangeResult, type MuteEnforcement, type MuteOptions, type MuteRecord, MuteService, type MuteStore, type ParticipantUpdateResult, type PresenceState, type QuotedMessage, type ReconnectOptions, type RemoveMuteResult, type RouterOptions, type SentMessage, SqliteMuteStore, type StoredMute, type TextContent, User, type UserData, type VideoContent, WhaNextApp, WhaNextError, type WhaNextErrorCode, type WhatsAppProvider, create, defineCommand, defineCommands, loadCommands, toWhaNextError };
+export { type AddMuteOptions, type AddMuteResult, type AppEvents, type AppHealth, type AppHealthStatus, ArgsParser, type AudioContent, type BooleanOption, Browser, type CacheOptions, type CacheStore, type CallEvent, type CallStatus, type ChangeResult, type CommandCatalogOptions, type CommandChatContext, type CommandConcurrency, type CommandContext, type CommandCooldown, type CommandDefinition, type CommandErrorHandler, type CommandGroupContext, type CommandGroupDefinition, type CommandGuard, type CommandHelpOptions, type CommandHooks, type CommandLocalization, type CommandMetadata, type CommandMiddleware, type CommandOptionDefinition, type CommandOptionSchema, type CommandOptionValue, type CommandOptionValues, type CommandRegistrar, CommandRouter, type CommandRuntimeServices, type CommandScope, type ConcurrencyStrategy, type ConnectionState, type ConnectionUpdate, type CreateOptions, DeferredReply, type DownloadedMedia, type DurationOption, type EnumOption, type ExecutableCommandDefinition, type GroupAccess, type GroupAddressingMode, type GroupParticipant, type GroupParticipantAction, type GroupParticipantsChanged, type GroupRole, type GroupSnapshot, type GuardResult, type ImageContent, type InviteResult, type LoadCommandsOptions, type LoadCommandsResult, type LoadedCommand, type LogContext, type LogEntry, type LogFormat, type LogLevel, type LogWriter, Logger, type LoggerConfig, type LoggerOptions, type LoginOptions, type MediaKind, type MediaSource, type MemberActionState, MemoryCache, type MemoryCacheStats, type MentionTarget, type Message, type MessageContent, type MessageKey, type MessageMedia, type MuteChangeResult, type MuteEnforcement, type MuteOptions, type MuteRecord, MuteService, type MuteStore, type NumberOption, ParsedCommandOptions, type ParticipantUpdateResult, type PresenceState, type QuotedMessage, type ReconnectOptions, type RegisteredCommand, type RemoveMuteResult, type ReplyOptions, type RouterOptions, type SentMessage, SqliteMuteStore, type StickerContent, type StoredMute, type StringOption, type TextContent, User, type UserData, type UserOption, type VideoContent, WhaNextApp, WhaNextError, type WhaNextErrorCode, type WhatsAppProvider, create, defineCommand, defineCommandGroup, defineCommands, defineSubcommand, guards, isCommandGroup, loadCommands, option, toWhaNextError };