@whanext/core 0.8.0 → 0.10.0

package/dist/index.js

@@ -2,18 +2,27 @@
 var MemoryCache = class {
   #entries = /* @__PURE__ */ new Map();
   #maxEntries;
+  #hits = 0;
+  #misses = 0;
+  #sets = 0;
+  #evictions = 0;
+  #expirations = 0;
   constructor(options = {}) {
     this.#maxEntries = Math.max(1, options.maxEntries ?? 1e3);
   }
   async get(key) {
     const entry = this.#entries.get(key);
     if (!entry) {
+      this.#misses += 1;
       return void 0;
     }
     if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) {
       this.#entries.delete(key);
+      this.#misses += 1;
+      this.#expirations += 1;
       return void 0;
     }
+    this.#hits += 1;
     this.#entries.delete(key);
     this.#entries.set(key, entry);
     return entry.value;
@@ -23,11 +32,14 @@ var MemoryCache = class {
     if (ttlMs !== void 0) {
       entry.expiresAt = Date.now() + ttlMs;
     }
+    this.#sets += 1;
+    this.#entries.delete(key);
     this.#entries.set(key, entry);
     while (this.#entries.size > this.#maxEntries) {
       const oldest = this.#entries.keys().next().value;
       if (oldest === void 0) return;
       this.#entries.delete(oldest);
+      this.#evictions += 1;
     }
   }
   async delete(key) {
@@ -36,6 +48,28 @@ var MemoryCache = class {
   async clear() {
     this.#entries.clear();
   }
+  prune(now = Date.now()) {
+    let removed = 0;
+    for (const [key, entry] of this.#entries) {
+      if (entry.expiresAt !== void 0 && entry.expiresAt <= now) {
+        this.#entries.delete(key);
+        removed += 1;
+      }
+    }
+    this.#expirations += removed;
+    return removed;
+  }
+  stats() {
+    return {
+      size: this.#entries.size,
+      maxEntries: this.#maxEntries,
+      hits: this.#hits,
+      misses: this.#misses,
+      sets: this.#sets,
+      evictions: this.#evictions,
+      expirations: this.#expirations
+    };
+  }
 };
 
 // src/errors/error.ts
@@ -298,94 +332,752 @@ var ArgsParser = class {
   }
 };
 
+// src/commands/command.ts
+function defineCommand(command) {
+  return command;
+}
+function defineSubcommand(command) {
+  return command;
+}
+function defineCommandGroup(group) {
+  return group;
+}
+function defineCommands(...commands) {
+  return commands;
+}
+function isCommandGroup(definition) {
+  return "subcommands" in definition;
+}
+
+// src/commands/concurrency.ts
+var CommandConcurrencyController = class {
+  #states = /* @__PURE__ */ new Map();
+  async run(key, options, execute) {
+    const strategy = options?.strategy ?? "parallel";
+    if (strategy === "parallel") {
+      await execute(new AbortController().signal);
+      return;
+    }
+    const max = Math.max(1, options?.max ?? 1);
+    const state = this.#states.get(key) ?? { active: 0, queue: [], controllers: /* @__PURE__ */ new Set() };
+    this.#states.set(key, state);
+    if (strategy === "replace") {
+      for (const controller2 of state.controllers) controller2.abort();
+      state.controllers.clear();
+    } else if (strategy === "reject" && state.active >= max) {
+      throw new WhaNextError("COMMAND_BUSY", "This command is already running.", {
+        context: { key, max },
+        recoverable: true
+      });
+    } else if (strategy === "queue" && state.active >= max) {
+      await new Promise((resolve2) => state.queue.push(resolve2));
+    }
+    const controller = new AbortController();
+    state.controllers.add(controller);
+    state.active += 1;
+    try {
+      await execute(controller.signal);
+    } finally {
+      state.controllers.delete(controller);
+      state.active -= 1;
+      state.queue.shift()?.();
+      if (state.active === 0 && state.queue.length === 0) {
+        this.#states.delete(key);
+      }
+    }
+  }
+};
+
+// src/commands/context.ts
+var CommandContextImplementation = class {
+  message;
+  user;
+  chat;
+  group;
+  command;
+  options;
+  args;
+  locale;
+  signal;
+  client;
+  messages;
+  mediaService;
+  groups;
+  members;
+  chats;
+  users;
+  muteService;
+  #lastReply;
+  constructor(options) {
+    this.message = options.message;
+    this.user = options.message.sender;
+    this.chat = { id: options.message.chatId, isGroup: options.message.isGroup };
+    this.command = options.command;
+    this.options = options.options;
+    this.args = options.args;
+    this.locale = options.locale;
+    this.signal = options.signal;
+    this.client = options.services;
+    this.messages = options.services.messages;
+    this.mediaService = options.services.media;
+    this.groups = options.services.groups;
+    this.members = options.services.members;
+    this.chats = options.services.chats;
+    this.users = options.services.users;
+    this.muteService = options.services.mute;
+    this.group = options.message.isGroup ? this.#createGroupContext(options.message) : void 0;
+    Object.assign(this, options.message);
+  }
+  async reply(content, options = {}) {
+    const sent = await this.messages.reply(this.message, normalizeContent(content));
+    this.#lastReply = sent;
+    this.#scheduleDeletion(sent, options.deleteAfterMs);
+    return sent;
+  }
+  async defer(content = "\u23F3 _Processando..._") {
+    const sent = await this.reply(content);
+    return new DeferredReply(this.messages, sent, (message) => {
+      this.#lastReply = message;
+    });
+  }
+  async edit(content) {
+    if (!this.#lastReply) {
+      throw new WhaNextError(
+        "MESSAGE_NOT_FOUND",
+        "There is no command reply to edit. Call reply() or defer() first."
+      );
+    }
+    const edited = await this.messages.edit(this.#lastReply, content);
+    this.#lastReply = edited;
+    return edited;
+  }
+  react(emoji) {
+    return this.messages.react(this.message, emoji);
+  }
+  unreact() {
+    return this.messages.unreact(this.message);
+  }
+  delete() {
+    return this.messages.delete(this.message);
+  }
+  async deleteReply(options = {}) {
+    if (!this.#lastReply) return;
+    if (options.deleteAfterMs !== void 0 && options.deleteAfterMs > 0) {
+      this.#scheduleDeletion(this.#lastReply, options.deleteAfterMs);
+      return;
+    }
+    await this.messages.delete(this.#lastReply);
+    this.#lastReply = void 0;
+  }
+  #createGroupContext(message) {
+    return {
+      id: message.chatId,
+      metadata: (refresh) => this.groups.metadata(message.chatId, refresh),
+      isUserAdmin: () => this.groups.isAdmin(message.chatId, message.senderIds),
+      isBotAdmin: () => this.groups.isCurrentUserAdmin(message.chatId)
+    };
+  }
+  #scheduleDeletion(message, delayMs) {
+    if (delayMs === void 0 || delayMs <= 0) return;
+    const timer = setTimeout(() => {
+      void this.messages.delete(message).catch(() => void 0);
+    }, delayMs);
+    timer.unref?.();
+  }
+};
+var DeferredReply = class {
+  #messages;
+  #message;
+  #onEdit;
+  constructor(messages, message, onEdit) {
+    this.#messages = messages;
+    this.#message = message;
+    this.#onEdit = onEdit;
+  }
+  async edit(content) {
+    this.#message = await this.#messages.edit(this.#message, content);
+    this.#onEdit(this.#message);
+    return this.#message;
+  }
+  delete() {
+    return this.#messages.delete(this.#message);
+  }
+};
+function createCommandContext(options) {
+  return new CommandContextImplementation(options);
+}
+function normalizeContent(content) {
+  return typeof content === "string" ? { text: content } : content;
+}
+
+// src/commands/options.ts
+var option = {
+  string(definition) {
+    return { kind: "string", ...definition };
+  },
+  number(definition) {
+    return { kind: "number", ...definition };
+  },
+  boolean(definition) {
+    return { kind: "boolean", ...definition };
+  },
+  user(definition) {
+    return { kind: "user", ...definition };
+  },
+  duration(definition) {
+    return { kind: "duration", ...definition };
+  },
+  enum(values, definition) {
+    return { kind: "enum", values, ...definition };
+  }
+};
+var ParsedCommandOptions = class {
+  #values;
+  constructor(values) {
+    this.#values = values;
+  }
+  get(name) {
+    return this.#values[name];
+  }
+  string(name) {
+    return this.get(name);
+  }
+  number(name) {
+    return this.get(name);
+  }
+  boolean(name) {
+    return this.get(name);
+  }
+  user(name) {
+    return this.get(name);
+  }
+  duration(name) {
+    return this.get(name);
+  }
+  enum(name) {
+    return this.get(name);
+  }
+  toJSON() {
+    return { ...this.#values };
+  }
+};
+async function parseCommandOptions(schema, tokens, message, users) {
+  const args = new ArgsParser(tokens);
+  const values = {};
+  for (const [name, definition] of Object.entries(schema ?? {})) {
+    const optional = definition.required !== true;
+    if (definition.kind === "user") {
+      const hasImplicitUser = message.mentionedUsers.length > 0 || message.quoted?.sender !== void 0;
+      if (optional && !hasImplicitUser && args.remaining === 0) {
+        values[name] = void 0;
+      } else {
+        values[name] = await users.resolve(message, args);
+      }
+      continue;
+    }
+    const argumentOptions = optional ? { optional: true } : void 0;
+    if (definition.kind === "string") {
+      const value = definition.rest ? args.rest() : args.string(name, argumentOptions);
+      if (definition.required && !value) {
+        throw missing(name);
+      }
+      if (value !== void 0 && definition.minLength !== void 0 && value.length < definition.minLength) {
+        throw invalid(name, value, `at least ${definition.minLength} characters`);
+      }
+      if (value !== void 0 && definition.maxLength !== void 0 && value.length > definition.maxLength) {
+        throw invalid(name, value, `at most ${definition.maxLength} characters`);
+      }
+      values[name] = value || void 0;
+    } else if (definition.kind === "number") {
+      const value = args.number(name, argumentOptions);
+      if (value !== void 0 && definition.min !== void 0 && value < definition.min) {
+        throw invalid(name, value, `at least ${definition.min}`);
+      }
+      if (value !== void 0 && definition.max !== void 0 && value > definition.max) {
+        throw invalid(name, value, `at most ${definition.max}`);
+      }
+      values[name] = value;
+    } else if (definition.kind === "boolean") {
+      values[name] = args.boolean(name, argumentOptions);
+    } else if (definition.kind === "duration") {
+      values[name] = args.duration(name, argumentOptions);
+    } else {
+      values[name] = args.enum(definition.values, name, argumentOptions);
+    }
+  }
+  if (schema !== void 0 && args.remaining > 0) {
+    throw new WhaNextError("ARGUMENT_INVALID", "Too many arguments were provided.", {
+      context: { remaining: args.remaining }
+    });
+  }
+  return new ParsedCommandOptions(values);
+}
+function missing(name) {
+  return new WhaNextError("ARGUMENT_MISSING", `The argument "${name}" is required.`, {
+    context: { name }
+  });
+}
+function invalid(name, received, expected) {
+  return new WhaNextError("ARGUMENT_INVALID", `The argument "${name}" must be ${expected}.`, {
+    context: { name, received, expected }
+  });
+}
+
+// src/services/user-service.ts
+var UserService = class {
+  #group;
+  constructor(group) {
+    this.#group = group;
+  }
+  async resolve(message, args) {
+    const mentioned = message.mentionedUsers[0];
+    let user;
+    if (mentioned) {
+      if (args.peek()?.startsWith("@")) {
+        args.skip();
+      }
+      user = mentioned;
+    } else if (message.quoted?.sender) {
+      user = message.quoted.sender;
+    } else {
+      user = args.user("membro");
+    }
+    return this.#group.resolveUser(message.chatId, user);
+  }
+  from(identity) {
+    if (!identity.includes("@")) {
+      return User.fromPhoneNumber(identity);
+    }
+    return User.fromIdentities([identity]);
+  }
+};
+
 // src/commands/router.ts
 var CommandRouter = class {
-  #commands = /* @__PURE__ */ new Map();
+  #roots = /* @__PURE__ */ new Map();
+  #definitions = /* @__PURE__ */ new Set();
   #prefix;
-  #group;
-  #onError;
-  constructor(group, options = {}) {
-    this.#group = group;
+  #services;
+  #legacyOnError;
+  #globalMiddleware = [];
+  #errorHandlers = [];
+  #cooldowns = /* @__PURE__ */ new Map();
+  #concurrency = new CommandConcurrencyController();
+  #beforeExecute;
+  #afterExecute;
+  #cooldownOperations = 0;
+  constructor(servicesOrGroup, options = {}) {
+    this.#services = isRuntimeServices(servicesOrGroup) ? servicesOrGroup : createLegacyServices(servicesOrGroup);
     this.#prefix = options.prefix ?? "!";
-    this.#onError = options.onError;
+    this.#legacyOnError = options.onError;
+    this.#beforeExecute = options.beforeExecute;
+    this.#afterExecute = options.afterExecute;
+    if (options.onCommandError) this.#errorHandlers.push(options.onCommandError);
     if (this.#prefix.length === 0 || /\s/.test(this.#prefix)) {
       throw new WhaNextError(
         "ARGUMENT_INVALID",
         "The command prefix cannot be empty or contain whitespace.",
-        {
-          context: { prefix: this.#prefix }
-        }
+        { context: { prefix: this.#prefix } }
       );
     }
   }
+  get prefix() {
+    return this.#prefix;
+  }
+  get size() {
+    return this.catalog({ includeHidden: true }).length;
+  }
   command(definition) {
-    const names = [definition.name, ...definition.aliases ?? []];
-    for (const name of names) {
-      const normalized = name.toLowerCase();
-      if (this.#commands.has(normalized)) {
+    this.#validateTree(definition, []);
+    for (const name of commandNames(definition)) {
+      const normalized = name.value.toLowerCase();
+      if (this.#roots.has(normalized)) {
         throw new WhaNextError(
           "ARGUMENT_INVALID",
           `The command "${normalized}" is already registered.`
         );
       }
-      this.#commands.set(normalized, definition);
+      this.#roots.set(normalized, {
+        definition,
+        ...name.locale ? { locale: name.locale } : {}
+      });
     }
+    this.#definitions.add(definition);
     return this;
   }
+  use(middleware) {
+    this.#globalMiddleware.push(middleware);
+    return this;
+  }
+  onError(handler) {
+    this.#errorHandlers.push(handler);
+    return () => {
+      const index = this.#errorHandlers.indexOf(handler);
+      if (index >= 0) this.#errorHandlers.splice(index, 1);
+    };
+  }
+  catalog(options = {}) {
+    const commands = [...this.#definitions].flatMap((definition) => flattenCommands(definition));
+    return commands.filter((command) => (options.includeHidden || !command.definition.hidden) && (!options.category || command.category === options.category));
+  }
+  categories() {
+    return [...new Set(this.catalog().map((command) => command.category))].sort();
+  }
+  has(path2) {
+    return this.find(path2) !== void 0;
+  }
+  values() {
+    return this.catalog({ includeHidden: true });
+  }
+  find(path2) {
+    const normalized = path2.trim().toLowerCase().split(/\s+/);
+    return this.catalog({ includeHidden: true }).find((command) => command.path.join(" ").toLowerCase() === normalized.join(" ") || command.aliases.some((alias) => alias.toLowerCase() === normalized.at(-1)));
+  }
+  async help(context, options = {}) {
+    const commands = this.catalog(options);
+    const title = options.title ?? (options.category ? `\u{1F4DA} *${options.category}*` : "\u{1F4DA} *Comandos*");
+    const lines = commands.map((command) => {
+      const usage = command.definition.usage ?? `${this.#prefix}${command.path.join(" ")}${formatOptions(command.definition)}`;
+      const description = context.locale ? command.definition.localizations?.[context.locale]?.description ?? command.definition.description : command.definition.description;
+      return `\u2022 *${usage}*
+  ${description}`;
+    });
+    const text = lines.length > 0 ? `${title}
+
+${lines.join("\n\n")}` : `${title}
+
+_Nenhum comando dispon\xEDvel._`;
+    return context.reply(text);
+  }
   async dispatch(message) {
     const text = message.text?.trim();
-    if (!text?.startsWith(this.#prefix)) {
-      return false;
-    }
+    if (!text?.startsWith(this.#prefix)) return false;
     const tokens = tokenize(text.slice(this.#prefix.length));
-    const name = tokens.shift()?.toLowerCase();
-    if (!name) {
-      return false;
-    }
-    const command = this.#commands.get(name);
-    if (!command) {
-      return false;
-    }
+    const rootName = tokens.shift()?.toLowerCase();
+    if (!rootName) return false;
+    const root = this.#roots.get(rootName);
+    if (!root) return false;
+    let resolved;
     try {
-      await this.#authorize(command, message);
-      await command.execute(message, new ArgsParser(tokens));
-      return true;
+      resolved = this.#resolve(root, tokens);
     } catch (error) {
-      const normalized = toWhaNextError(error, { command: command.name, messageId: message.id });
-      if (this.#onError) {
-        await this.#onError(normalized, message);
+      const normalized = toWhaNextError(error, { command: root.definition.name, messageId: message.id });
+      const fallbackDefinition = {
+        ...root.definition,
+        execute: () => void 0
+      };
+      const context2 = createCommandContext({
+        message,
+        command: {
+          definition: fallbackDefinition,
+          root: root.definition,
+          path: [root.definition.name],
+          aliases: root.definition.aliases ?? [],
+          category: root.definition.category ?? "general"
+        },
+        options: new ParsedCommandOptions({}),
+        args: new ArgsParser(tokens),
+        services: this.#services,
+        signal: new AbortController().signal,
+        ...root.locale ? { locale: root.locale } : {}
+      });
+      if (root.definition.hooks?.onError) {
+        await root.definition.hooks.onError(context2, normalized);
+        return true;
+      }
+      if (this.#errorHandlers.length > 0) {
+        for (const handler of this.#errorHandlers) await handler(context2, normalized);
+        return true;
+      }
+      if (this.#legacyOnError) {
+        await this.#legacyOnError(normalized, message);
         return true;
       }
       throw normalized;
     }
+    const legacyArgs = new ArgsParser(resolved.tokens);
+    let context;
+    try {
+      const parsedOptions = await parseCommandOptions(
+        resolved.registered.definition.options,
+        resolved.tokens,
+        message,
+        this.#services.users
+      );
+      const concurrency = [...resolved.layers].reverse().find((layer) => layer.concurrency)?.concurrency;
+      const concurrencyKey = this.#executionKey(
+        resolved,
+        message,
+        concurrency?.scope ?? "user-chat"
+      );
+      await this.#concurrency.run(
+        concurrencyKey,
+        concurrency,
+        async (signal) => {
+          context = createCommandContext({
+            message,
+            command: resolved.registered,
+            options: parsedOptions,
+            args: legacyArgs,
+            services: this.#services,
+            signal,
+            ...resolved.locale ? { locale: resolved.locale } : {}
+          });
+          await this.#authorize(resolved.layers, context);
+          this.#consumeCooldown(resolved, context);
+          await this.#execute(resolved, context);
+        }
+      );
+      return true;
+    } catch (error) {
+      const normalized = toWhaNextError(error, {
+        command: resolved.registered.path.join(" "),
+        messageId: message.id
+      });
+      context ??= createCommandContext({
+        message,
+        command: resolved.registered,
+        options: new ParsedCommandOptions({}),
+        args: legacyArgs,
+        services: this.#services,
+        signal: new AbortController().signal,
+        ...resolved.locale ? { locale: resolved.locale } : {}
+      });
+      if (await this.#handleError(resolved, context, normalized)) return true;
+      throw normalized;
+    }
+  }
+  #resolve(root, inputTokens) {
+    const tokens = [...inputTokens];
+    const layers = [root.definition];
+    let current = root.definition;
+    let locale = root.locale;
+    while (isCommandGroup(current)) {
+      const name = tokens.shift()?.toLowerCase();
+      if (!name) {
+        throw new WhaNextError("ARGUMENT_MISSING", `Choose a subcommand for "${current.name}".`, {
+          context: { command: current.name }
+        });
+      }
+      const found = findChild(current.subcommands, name);
+      if (!found) {
+        throw new WhaNextError("ARGUMENT_INVALID", `The subcommand "${name}" does not exist.`, {
+          context: { command: current.name, subcommand: name }
+        });
+      }
+      current = found.definition;
+      locale ??= found.locale;
+      layers.push(current);
+    }
+    const path2 = layers.map((definition) => definition.name);
+    return {
+      registered: {
+        definition: current,
+        root: root.definition,
+        path: path2,
+        aliases: current.aliases ?? [],
+        category: current.category ?? root.definition.category ?? "general"
+      },
+      layers,
+      tokens,
+      ...locale ? { locale } : {}
+    };
   }
-  async #authorize(command, message) {
-    if (command.onlyGroup && !message.isGroup) {
+  async #authorize(layers, context) {
+    for (const command of layers) {
+      await this.#authorizeLegacy(command, context);
+      for (const guard of command.guards ?? []) await runGuard(guard, context);
+    }
+  }
+  async #authorizeLegacy(command, context) {
+    if (command.onlyGroup && !context.isGroup) {
       throw new WhaNextError("COMMAND_NOT_ALLOWED", "This command can only be used in groups.");
     }
-    if (command.onlyPrivate && message.isGroup) {
-      throw new WhaNextError(
-        "COMMAND_NOT_ALLOWED",
-        "This command can only be used in private chats."
-      );
+    if (command.onlyPrivate && context.isGroup) {
+      throw new WhaNextError("COMMAND_NOT_ALLOWED", "This command can only be used in private chats.");
     }
-    if (command.onlyAdmin && !await this.#group.isAdmin(message.chatId, message.senderIds)) {
-      throw new WhaNextError(
-        "COMMAND_NOT_ALLOWED",
-        "This command can only be used by group administrators."
-      );
+    if (command.onlyAdmin && !await this.#services.groups.isAdmin(context.chatId, context.senderIds)) {
+      throw new WhaNextError("COMMAND_NOT_ALLOWED", "This command can only be used by group administrators.");
     }
-    if (command.botMustBeAdmin && !await this.#group.isCurrentUserAdmin(message.chatId)) {
-      throw new WhaNextError(
-        "BOT_NOT_ADMIN",
-        "The connected WhatsApp account must be a group administrator."
-      );
+    if (command.botMustBeAdmin && !await this.#services.groups.isCurrentUserAdmin(context.chatId)) {
+      throw new WhaNextError("BOT_NOT_ADMIN", "The connected WhatsApp account must be a group administrator.");
+    }
+  }
+  async #execute(resolved, context) {
+    const hooks = resolved.layers.map((layer) => layer.hooks).filter(Boolean);
+    if (this.#beforeExecute) await this.#beforeExecute(context);
+    for (const hook of hooks) await hook.beforeExecute?.(context);
+    const middleware = [
+      ...this.#globalMiddleware,
+      ...resolved.layers.flatMap((layer) => layer.middleware ?? [])
+    ];
+    await composeMiddleware(middleware, context, async () => {
+      await resolved.registered.definition.execute(context, context.args);
+    });
+    for (const hook of [...hooks].reverse()) await hook.afterExecute?.(context);
+    if (this.#afterExecute) await this.#afterExecute(context);
+  }
+  #consumeCooldown(resolved, context) {
+    const config = [...resolved.layers].reverse().find((layer) => layer.cooldown)?.cooldown;
+    if (!config || config.durationMs <= 0) return;
+    const key = this.#executionKey(resolved, context, config.scope ?? "user");
+    const now = Date.now();
+    this.#cooldownOperations += 1;
+    if (this.#cooldownOperations % 256 === 0) this.#pruneCooldowns(now);
+    const expiresAt = this.#cooldowns.get(key) ?? 0;
+    if (expiresAt > now) {
+      throw new WhaNextError("COMMAND_COOLDOWN", "This command is on cooldown.", {
+        context: { retryAfterMs: expiresAt - now, key },
+        recoverable: true
+      });
+    }
+    this.#cooldowns.set(key, now + config.durationMs);
+  }
+  #pruneCooldowns(now) {
+    for (const [key, expiresAt] of this.#cooldowns) {
+      if (expiresAt <= now) this.#cooldowns.delete(key);
+    }
+  }
+  #executionKey(resolved, message, scope) {
+    const command = resolved.registered.path.join("/").toLowerCase();
+    if (scope === "global") return command;
+    if (scope === "user") return `${command}:user:${message.senderId}`;
+    if (scope === "chat") return `${command}:chat:${message.chatId}`;
+    return `${command}:user-chat:${message.senderId}:${message.chatId}`;
+  }
+  async #handleError(resolved, context, error) {
+    for (const layer of [...resolved.layers].reverse()) {
+      if (layer.hooks?.onError) {
+        await layer.hooks.onError(context, error);
+        return true;
+      }
+    }
+    if (this.#errorHandlers.length > 0) {
+      for (const handler of this.#errorHandlers) await handler(context, error);
+      return true;
+    }
+    if (this.#legacyOnError) {
+      await this.#legacyOnError(error, context.message);
+      return true;
+    }
+    return false;
+  }
+  #validateTree(definition, parents) {
+    if (!definition.name.trim() || /\s/.test(definition.name)) {
+      throw new WhaNextError("ARGUMENT_INVALID", "Command names cannot be empty or contain whitespace.", {
+        context: { name: definition.name }
+      });
+    }
+    for (const name of commandNames(definition)) {
+      if (!name.value.trim() || /\s/.test(name.value)) {
+        throw new WhaNextError(
+          "ARGUMENT_INVALID",
+          "Command names and aliases cannot be empty or contain whitespace.",
+          { context: { name: name.value } }
+        );
+      }
+    }
+    if (!isCommandGroup(definition)) return;
+    if (definition.subcommands.length === 0) {
+      throw new WhaNextError("ARGUMENT_INVALID", `The command group "${definition.name}" is empty.`);
+    }
+    const names = /* @__PURE__ */ new Set();
+    for (const child of definition.subcommands) {
+      for (const name of commandNames(child)) {
+        const normalized = name.value.toLowerCase();
+        if (names.has(normalized)) {
+          throw new WhaNextError("ARGUMENT_INVALID", `Duplicate subcommand "${normalized}".`, {
+            context: { path: [...parents, definition.name].join(" ") }
+          });
+        }
+        names.add(normalized);
+      }
+      this.#validateTree(child, [...parents, definition.name]);
     }
   }
 };
+async function runGuard(guard, context) {
+  const result = await guard(context);
+  if (result === void 0 || result === true) return;
+  const normalized = result === false ? { allowed: false } : result;
+  if (normalized.allowed) return;
+  throw new WhaNextError(
+    normalized.code ?? "COMMAND_NOT_ALLOWED",
+    normalized.message ?? "This command is not allowed in the current context."
+  );
+}
+async function composeMiddleware(middleware, context, execute) {
+  let index = -1;
+  const dispatch = async (position) => {
+    if (position <= index) throw new Error("next() was called more than once.");
+    index = position;
+    const current = middleware[position];
+    if (!current) return execute();
+    await current(context, () => dispatch(position + 1));
+  };
+  await dispatch(0);
+}
+function commandNames(definition) {
+  const names = [
+    definition.name,
+    ...definition.aliases ?? []
+  ].map((value) => ({ value }));
+  for (const [locale, localization] of Object.entries(definition.localizations ?? {})) {
+    if (localization.name) names.push({ value: localization.name, locale });
+    for (const alias of localization.aliases ?? []) names.push({ value: alias, locale });
+  }
+  return names;
+}
+function findChild(definitions, name) {
+  for (const definition of definitions) {
+    const found = commandNames(definition).find((candidate) => candidate.value.toLowerCase() === name);
+    if (found) return { definition, ...found.locale ? { locale: found.locale } : {} };
+  }
+  return void 0;
+}
+function flattenCommands(root, parents = []) {
+  if (isCommandGroup(root)) {
+    return root.subcommands.flatMap((child) => flattenCommands(child, [...parents, root]));
+  }
+  const pathDefinitions = [...parents, root];
+  return [{
+    definition: root,
+    root: pathDefinitions[0] ?? root,
+    path: pathDefinitions.map((definition) => definition.name),
+    aliases: root.aliases ?? [],
+    category: root.category ?? [...parents].reverse().find((parent) => parent.category)?.category ?? "general"
+  }];
+}
+function formatOptions(definition) {
+  return Object.entries(definition.options ?? {}).map(([name, option2]) => option2.required ? ` <${name}>` : ` [${name}]`).join("");
+}
 function tokenize(input) {
   return input.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map((token) => token.replace(/^(["'])(.*)\1$/, "$2")) ?? [];
 }
+function isRuntimeServices(value) {
+  return "groups" in value && "messages" in value;
+}
+function createLegacyServices(group) {
+  const unavailable = new Proxy({}, {
+    get() {
+      return () => {
+        throw new WhaNextError(
+          "PROVIDER_ERROR",
+          "This CommandRouter was created without the full application services."
+        );
+      };
+    }
+  });
+  return {
+    groups: group,
+    users: new UserService(group),
+    messages: unavailable,
+    media: unavailable,
+    members: unavailable,
+    chats: unavailable,
+    mute: unavailable
+  };
+}
 
 // src/logger/logger.ts
 var priorities = {
@@ -1190,35 +1882,6 @@ var MessageService = class {
   }
 };
 
-// src/services/user-service.ts
-var UserService = class {
-  #group;
-  constructor(group) {
-    this.#group = group;
-  }
-  async resolve(message, args) {
-    const mentioned = message.mentionedUsers[0];
-    let user;
-    if (mentioned) {
-      if (args.peek()?.startsWith("@")) {
-        args.skip();
-      }
-      user = mentioned;
-    } else if (message.quoted?.sender) {
-      user = message.quoted.sender;
-    } else {
-      user = args.user("membro");
-    }
-    return this.#group.resolveUser(message.chatId, user);
-  }
-  from(identity) {
-    if (!identity.includes("@")) {
-      return User.fromPhoneNumber(identity);
-    }
-    return User.fromIdentities([identity]);
-  }
-};
-
 // src/app/whanext-app.ts
 var WhaNextApp = class {
   message;
@@ -1229,6 +1892,7 @@ var WhaNextApp = class {
   user;
   mute;
   logger;
+  commands;
   #provider;
   #phone;
   #events = new TypedEventEmitter();
@@ -1251,10 +1915,19 @@ var WhaNextApp = class {
     const muteEnabled = options.mute?.enabled === true || options.mute?.store !== void 0;
     const muteStore = muteEnabled ? options.mute?.store ?? new SqliteMuteStore(options.mute?.database) : void 0;
     this.mute = new MuteService(provider, muteStore);
-    this.#router = new CommandRouter(this.group, {
+    this.commands = new CommandRouter({
+      messages: this.message,
+      media: this.media,
+      groups: this.group,
+      members: this.member,
+      chats: this.chat,
+      users: this.user,
+      mute: this.mute
+    }, {
       ...options.router,
       ...options.prefix !== void 0 ? { prefix: options.prefix } : {}
     });
+    this.#router = this.commands;
     this.#bind();
     this.logger.debug("Application initialized", {
       muteEnabled: this.mute.enabled,
@@ -1659,6 +2332,12 @@ var BaileysProvider = class {
   #logger;
   #messageStore = /* @__PURE__ */ new Map();
   #messageCacheSize;
+  #groupMetadataCache = /* @__PURE__ */ new Map();
+  #groupMetadataRequests = /* @__PURE__ */ new Map();
+  #groupMetadataGenerations = /* @__PURE__ */ new Map();
+  #groupMetadataCacheEnabled;
+  #groupMetadataCacheTtlMs;
+  #groupMetadataCacheSize;
   #socket;
   #saveCredentials;
   #saveQueue = Promise.resolve();
@@ -1670,6 +2349,9 @@ var BaileysProvider = class {
     this.#options = options;
     this.#logger = options.logger ?? new Logger("silent");
     this.#messageCacheSize = Math.max(1, options.messageCacheSize ?? 1e3);
+    this.#groupMetadataCacheEnabled = options.groupMetadataCache?.enabled !== false;
+    this.#groupMetadataCacheTtlMs = Math.max(1, options.groupMetadataCache?.ttlMs ?? 3e5);
+    this.#groupMetadataCacheSize = Math.max(1, options.groupMetadataCache?.maxEntries ?? 1e3);
   }
   on(event, listener) {
     return this.#events.on(event, listener);
@@ -1694,6 +2376,7 @@ var BaileysProvider = class {
         markOnlineOnConnect: false,
         enableAutoSessionRecreation: true,
         enableRecentMessageCache: true,
+        cachedGroupMetadata: async (jid) => this.#getGroupMetadata(jid),
         getMessage: async (key) => this.#messageStore.get(this.#messageStoreKey(key))?.message ?? void 0
       });
       this.#socket = socket;
@@ -1817,7 +2500,7 @@ var BaileysProvider = class {
     await this.#requireSocket().sendMessage(key.chatId, { delete: this.#toWaKey(key) });
   }
   async getGroup(groupId) {
-    const metadata = await this.#requireSocket().groupMetadata(groupId);
+    const metadata = await this.#getGroupMetadata(groupId);
     return {
       id: metadata.id,
       subject: metadata.subject,
@@ -1835,6 +2518,7 @@ var BaileysProvider = class {
   async setGroupAccess(groupId, access) {
     const setting = access === "closed" ? "announcement" : "not_announcement";
     await this.#requireSocket().groupSettingUpdate(groupId, setting);
+    this.#invalidateGroupMetadata(groupId);
   }
   async getGroupInviteCode(groupId) {
     const code = await this.#requireSocket().groupInviteCode(groupId);
@@ -1865,6 +2549,7 @@ var BaileysProvider = class {
   }
   async updateParticipant(groupId, memberId, action) {
     const [result] = await this.#requireSocket().groupParticipantsUpdate(groupId, [memberId], action);
+    this.#invalidateGroupMetadata(groupId);
     const status = result?.status ?? "unknown";
     return {
       success: status === "200",
@@ -1897,10 +2582,14 @@ var BaileysProvider = class {
     });
     socket.ev.on("groups.update", (groups) => {
       for (const group of groups) {
-        if (group.id) void this.#events.emit("groupChanged", { groupId: group.id });
+        if (group.id) {
+          this.#invalidateGroupMetadata(group.id);
+          void this.#events.emit("groupChanged", { groupId: group.id });
+        }
       }
     });
     socket.ev.on("group-participants.update", (update) => {
+      this.#invalidateGroupMetadata(update.id);
       const change = this.#groupParticipantsChanged(update);
       void this.#events.emit("groupParticipantsChanged", change);
       const { id } = update;
@@ -2084,6 +2773,52 @@ var BaileysProvider = class {
       if (oldest) this.#messageStore.delete(oldest);
     }
   }
+  async #getGroupMetadata(groupId) {
+    if (this.#groupMetadataCacheEnabled) {
+      const cached = this.#groupMetadataCache.get(groupId);
+      if (cached && cached.expiresAt > Date.now()) {
+        this.#groupMetadataCache.delete(groupId);
+        this.#groupMetadataCache.set(groupId, cached);
+        return cached.value;
+      }
+      if (cached) this.#groupMetadataCache.delete(groupId);
+    }
+    const generation = this.#groupMetadataGenerations.get(groupId) ?? 0;
+    const pending = this.#groupMetadataRequests.get(groupId);
+    if (pending?.generation === generation) return pending.promise;
+    const request = this.#requireSocket().groupMetadata(groupId);
+    const requestEntry = { generation, promise: request };
+    this.#groupMetadataRequests.set(groupId, requestEntry);
+    try {
+      const metadata = await request;
+      if ((this.#groupMetadataGenerations.get(groupId) ?? 0) === generation) {
+        this.#rememberGroupMetadata(groupId, metadata);
+      }
+      return metadata;
+    } finally {
+      if (this.#groupMetadataRequests.get(groupId) === requestEntry) {
+        this.#groupMetadataRequests.delete(groupId);
+      }
+    }
+  }
+  #rememberGroupMetadata(groupId, metadata) {
+    if (!this.#groupMetadataCacheEnabled) return;
+    this.#groupMetadataCache.delete(groupId);
+    this.#groupMetadataCache.set(groupId, {
+      value: metadata,
+      expiresAt: Date.now() + this.#groupMetadataCacheTtlMs
+    });
+    while (this.#groupMetadataCache.size > this.#groupMetadataCacheSize) {
+      const oldest = this.#groupMetadataCache.keys().next().value;
+      if (oldest === void 0) return;
+      this.#groupMetadataCache.delete(oldest);
+    }
+  }
+  #invalidateGroupMetadata(groupId) {
+    this.#groupMetadataCache.delete(groupId);
+    const generation = this.#groupMetadataGenerations.get(groupId) ?? 0;
+    this.#groupMetadataGenerations.set(groupId, generation + 1);
+  }
   #messageStoreKey(key) {
     const chatId = "chatId" in key ? key.chatId : key.remoteJid;
     return `${chatId ?? ""}:${key.id ?? ""}`;
@@ -2098,6 +2833,10 @@ async function create(options = {}) {
     browser: options.browser ?? "windows" /* Windows */,
     logger: logger.child("provider"),
     ...options.messageCacheSize !== void 0 ? { messageCacheSize: options.messageCacheSize } : {},
+    groupMetadataCache: {
+      ...options.cache?.groupTtlMs !== void 0 ? { ttlMs: options.cache.groupTtlMs } : {},
+      ...options.cache?.memoryMaxEntries !== void 0 ? { maxEntries: options.cache.memoryMaxEntries } : {}
+    },
     ...options.reconnect ? { reconnect: options.reconnect } : {}
   });
   return new WhaNextApp(provider, {
@@ -2110,13 +2849,47 @@ async function create(options = {}) {
   }, logger);
 }
 
-// src/commands/command.ts
-function defineCommand(command) {
-  return command;
-}
-function defineCommands(...commands) {
-  return commands;
-}
+// src/commands/guards.ts
+var guards = {
+  group() {
+    return (context) => context.isGroup || {
+      allowed: false,
+      code: "COMMAND_NOT_ALLOWED",
+      message: "This command can only be used in groups."
+    };
+  },
+  private() {
+    return (context) => !context.isGroup || {
+      allowed: false,
+      code: "COMMAND_NOT_ALLOWED",
+      message: "This command can only be used in private chats."
+    };
+  },
+  userAdmin() {
+    return async (context) => context.isGroup && await context.groups.isAdmin(context.chatId, context.senderIds) || {
+      allowed: false,
+      code: "COMMAND_NOT_ALLOWED",
+      message: "This command can only be used by group administrators."
+    };
+  },
+  botAdmin() {
+    return async (context) => context.isGroup && await context.groups.isCurrentUserAdmin(context.chatId) || {
+      allowed: false,
+      code: "BOT_NOT_ADMIN",
+      message: "The connected WhatsApp account must be a group administrator."
+    };
+  },
+  botEnabled(check) {
+    return async (context) => await check(context) || {
+      allowed: false,
+      code: "COMMAND_NOT_ALLOWED",
+      message: "Commands are disabled in this chat."
+    };
+  },
+  custom(guard) {
+    return guard;
+  }
+};
 
 // src/commands/load-commands.ts
 import { readdir } from "fs/promises";
@@ -2189,23 +2962,31 @@ async function importCommands(filePath) {
   return definitions;
 }
 function isCommandDefinition(value) {
-  return typeof value === "object" && value !== null && typeof value.name === "string" && typeof value.execute === "function";
+  const candidate = value;
+  return typeof value === "object" && value !== null && typeof candidate.name === "string" && (typeof candidate.execute === "function" || Array.isArray(candidate.subcommands));
 }
 export {
   ArgsParser,
   Browser,
   CommandRouter,
+  DeferredReply,
   Logger,
   MemoryCache,
   MuteService,
+  ParsedCommandOptions,
   SqliteMuteStore,
   User,
   WhaNextApp,
   WhaNextError,
   create,
   defineCommand,
+  defineCommandGroup,
   defineCommands,
+  defineSubcommand,
+  guards,
+  isCommandGroup,
   loadCommands,
+  option,
   toWhaNextError
 };
 //# sourceMappingURL=index.js.map