morpho-socket 0.0.0-stage → 0.3.0

package/packages/commands/README.md

@@ -0,0 +1,78 @@
+# morpho-socket/commands
+
+The generic half of a command bot: **load commands from folders**, find them by name or alias, run them with the usual guards (owner / admin / bot-admin), and hook in everything that is your bot's own business (per-group switches, antiflood, "did you mean…", stats).
+
+```js
+const path = require("path")
+const { createCommands } = require("morpho-socket/commands")
+
+const commands = createCommands({
+  dirs: [                                       // use absolute paths: each file is loaded with require()
+    { type: "user",  dir: path.join(__dirname, "commands", "user")  },
+    { type: "admin", dir: path.join(__dirname, "commands", "admin") },
+    { type: "owner", dir: path.join(__dirname, "commands", "owner") },
+  ],
+  log: (level, text) => console.log(level, text),
+  messages: { notAdmin: "You are not an admin here.", botNotAdmin: "I need to be an admin.", notOwner: "Owner only.", notGroup: "Groups only." },
+})
+commands.load()   // warns about: repeated names/aliases, a mistyped "aliasee" key, broken files, commands without name/run
+
+await commands.dispatch(g, {                     // the command comes from g.command (the group's prefix is already applied)
+  before:     async (g, command, parsed) => { /* per-group switches, antiflood… return false to stop */ },
+  onNotFound: async (g, parsed) => { /* "unknown command" */ },
+  run:        (g, command, args, exec) => presence.during(g.sock, g.chatId, "composing", exec, { delayMs: 1200 }),
+})
+```
+
+`dispatch` returns `true` when the text was a command call (found or not) and `false` when it wasn't, so you can route non-commands elsewhere.
+
+## A command
+
+```js
+// commands/user/economy/balance.js
+module.exports = {
+  name: "balance",
+  aliases: ["bal", "coins"],
+  access: "user",                       // "user" | "admin" | "owner" — optional, falls back to the folder's `type`
+  desc: "Shows your coins",             // any extra field is kept (desc, usage, cooldown…) for your own use
+  async run(g, { name, args, argText }) {
+    await g.reply("You have 10 coins")
+  },
+}
+```
+
+- **Folders become categories:** `economy/balance.js` → `command.category = "economy"` (top-level files are `"general"`).
+- Files starting with `_` and `*.test.js` are ignored (helpers and tests can live next to commands).
+- A command's own `access` wins over the folder `type`.
+- `admin` requires a group, an admin sender **and** an admin bot; `owner` requires `g.isOwner`. The texts are configurable through `messages` (`notGroup`, `botNotAdmin`, `notAdmin`, `notOwner`).
+- One broken file never stops the others from loading.
+
+## Parsing text yourself
+
+```js
+const { parse } = require("morpho-socket/commands")
+parse("!Hi  a  b", "!")        // { name: "hi", args: ["a", "b"], argText: "a  b", prefix: "!" }
+
+await commands.dispatch(g, { text: "!hi", prefix: "!" })   // parse something other than g.command
+```
+
+## Antiflood
+
+More than N commands in X seconds → the person is ignored for Y seconds. The warning goes out **once per block**; everything else is silently ignored.
+
+```js
+const { createAntiflood } = require("morpho-socket/commands")
+const flood = createAntiflood()
+
+// inside `before`:
+const r = flood.check(`${g.clientId}:${g.user.number}`, { enabled: true, commands: 5, windowSec: 10, blockSec: 30 })
+if (!r.ok) { if (r.warn) await g.reply(`Slow down — wait ${r.wait}s`); return false }
+```
+
+`check` returns `{ ok, warn?, wait?, fresh? }`. Idle entries are cleaned up automatically.
+
+## API
+
+`createCommands({ dirs, log, messages })` → `{ load, dispatch, parse, get(name), has(name), unique(), map, size }` — `unique()` is the real commands (the map holds every name *and* alias).
+
+Also exported: `createAntiflood`, `parse`, `DEFAULT_MESSAGES`. `g` comes from [`context`](../context), but anything with `isOwner`, `isAdmin()`, `isBotAdmin()` and `reply()` works.

package/packages/commands/antiflood.js

@@ -0,0 +1,39 @@
+// Command limit per person: more than N commands in X seconds => ignored for Y seconds.
+// The warning goes out ONCE per block (the bot doesn't spam); the rest is silently ignored.
+function createAntiflood() {
+  const map = new Map() // key -> { marks, until, warned }
+
+  // cfg: { enabled, commands, windowSec, blockSec }. Returns { ok, warn, wait, fresh }
+  function check(key, cfg, now = Date.now()) {
+    if (!cfg.enabled) return { ok: true }
+    let e = map.get(key)
+    if (!e) { e = { marks: [], until: 0, warned: false }; map.set(key, e) }
+
+    if (e.until > now) {
+      const warn = !e.warned
+      e.warned = true
+      return { ok: false, warn, wait: Math.ceil((e.until - now) / 1000) }
+    }
+
+    e.warned = false
+    e.marks = e.marks.filter(t => now - t < cfg.windowSec * 1000)
+    e.marks.push(now)
+    if (e.marks.length > cfg.commands) {
+      e.until = now + cfg.blockSec * 1000
+      e.warned = true
+      e.marks = []
+      return { ok: false, warn: true, wait: cfg.blockSec, fresh: true }
+    }
+    return { ok: true }
+  }
+
+  const timer = setInterval(() => {
+    const now = Date.now()
+    for (const [k, e] of map) if (e.until < now && !e.marks.some(x => now - x < 300_000)) map.delete(k)
+  }, 600_000)
+  timer.unref?.()
+
+  return { check, size: () => map.size }
+}
+
+module.exports = { createAntiflood }

package/packages/commands/index.js

@@ -0,0 +1,116 @@
+// @morpho/commands
+//
+// The generic half of a command bot: load commands from folders, find them by name/alias, parse "<prefix>name args",
+// and run them with the usual guards (owner / admin / bot-admin) and hooks for everything that is the bot's own business
+// (per-group enable/disable, antiflood, "did you mean", stats...).
+//
+//   const commands = createCommands({ dirs: [{ dir }], log: console.log })        // (type = default access of that dir; default "user")
+//   commands.load()
+//   await commands.dispatch(g, { text, prefix, before, onNotFound, run })
+//
+// A command is { name, aliases?, access?: "user"|"admin"|"owner", run(g, { name, args, argText }), ...anything else (desc, usage...) }.
+// Nested folders become categories: dir/economy/saldo.js -> command.category = "economy".
+// `g` is a context from @morpho/context (or anything with isOwner / isAdmin() / isBotAdmin() / reply()).
+const fs = require("fs")
+const path = require("path")
+const { createAntiflood } = require("./antiflood")
+
+const DEFAULT_MESSAGES = {
+  botNotAdmin: "❌ Eu não admin desse grupo.",
+  notAdmin: "❌ Você não é admin desse grupo.",
+  notOwner: "❌ Você é não dono.",
+  notGroup: "❌ Isso só funciona em grupo."
+}
+
+// "<prefix>name a b  c" -> { name: "name", args: ["a", "b", "c"], argText: "a b  c", prefix } | null
+// (the "g" from @morpho/context already does this: g.command. This is for plain text, or a g that has no .command)
+function parse(text, prefix) {
+  if (!text || !prefix || !text.startsWith(prefix)) return null
+  const rest = text.slice(prefix.length).trim()
+  if (!rest) return null
+  const [raw, ...args] = rest.split(/ +/)
+  return { name: raw.toLowerCase(), args, argText: rest.slice(raw.length).trim(), prefix }
+}
+
+// opts: { dirs: [{ type, dir }], log(level, text) }
+function createCommands({ dirs = [], log = () => {}, messages = {} } = {}) {
+  const map = new Map() // name or alias -> command
+  const texts = { ...DEFAULT_MESSAGES, ...messages }
+
+  const register = (name, command, file, dupes) => {
+    const old = map.get(name)
+    if (old && old !== command) dupes.push(`"${name}": ${old.file} and ${file}`)
+    map.set(name, command)
+  }
+
+  // Folders can be nested: dir/economy/saldo.js -> category "economy". Files starting with "_" and "*.test.js" are skipped (helpers).
+  // Access: command.access ("user" | "admin" | "owner") wins; else the dir's `type`; else "user".
+  function walk(root, dir, out = []) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) walk(root, full, out)
+      else if (entry.name.endsWith(".js") && !entry.name.startsWith("_") && !entry.name.endsWith(".test.js")) out.push(full)
+    }
+    return out.sort()
+  }
+
+  function load() {
+    map.clear()
+    const dupes = []
+    for (const { type = "user", dir } of dirs) {
+      if (!fs.existsSync(dir)) continue
+      for (const full of walk(dir, dir)) {
+        const rel = path.relative(dir, full), file = rel.split(path.sep).join("/")
+        let command
+        try { command = require(full) } // a broken file doesn't stop the others from loading
+        catch (e) { log("error", `Failed to load ${file}: ${e.message}`); continue }
+        if (!command?.name || typeof command?.run !== "function") { log("error", `Invalid command: ${file}`); continue }
+
+        // typo guard: "aliasee", "alias"... silently registered nothing before
+        for (const k of Object.keys(command)) if (/^alias/i.test(k) && k !== "aliases") log("warn", `${file}: unknown key "${k}" (did you mean "aliases"?)`)
+
+        command.access = command.type = command.access || type
+        command.category = command.category || (rel.includes(path.sep) ? rel.split(path.sep)[0] : "general")
+        command.file = file
+        register(command.name, command, file, dupes)
+        for (const alias of command.aliases || []) register(alias, command, file, dupes)
+      }
+    }
+    if (dupes.length) log("warn", `Repeated names/aliases (the last one loaded wins):\n   - ${dupes.join("\n   - ")}`)
+    return map
+  }
+
+  // the real commands (the Map holds every name AND alias)
+  const unique = () => [...new Set(map.values())]
+
+  // opts:
+  //   before(g, command, parsed)  -> false to stop (the hook answers by itself). Runs before the guards. (per-group switches, antiflood...)
+  //   onNotFound(g, parsed)       command doesn't exist
+  //   run(g, command, args, exec) wraps the execution (e.g. presence "typing…"); exec() runs the command
+  // returns true when the text was a command call (found or not), false otherwise.
+  // The command comes from g.command (@morpho/context: the group's prefix is already applied). Pass { text, prefix } only
+  // to parse something else (or when your g has no .command).
+  async function dispatch(g, { text, prefix, before, onNotFound, run } = {}) {
+    const parsed = (text !== undefined || prefix !== undefined) ? parse(text, prefix) : (g.command ?? null)
+    if (!parsed) return false
+    const command = map.get(parsed.name)
+    if (!command) { await onNotFound?.(g, parsed); return true }
+
+    if (before && (await before(g, command, parsed)) === false) return true
+
+    if (command.type === "admin") {
+      if (g.isGroup === false) { await g.reply(texts.notGroup); return true }          // admin commands are group commands
+      if (!(await g.isBotAdmin())) { await g.reply(texts.botNotAdmin); return true }
+      if (!(await g.isAdmin())) { await g.reply(texts.notAdmin); return true }
+    }
+    if (command.type === "owner" && !g.isOwner) { await g.reply(texts.notOwner); return true }
+
+    const exec = () => command.run(g, parsed)
+    await (run ? run(g, command, parsed.args, exec) : exec())
+    return true
+  }
+
+  return { load, get: name => map.get(name), has: name => map.has(name), unique, dispatch, parse, map, get size() { return map.size } }
+}
+
+module.exports = { createCommands, createAntiflood, parse, DEFAULT_MESSAGES }

package/packages/commands/package.json

@@ -0,0 +1 @@
+{ "name": "@morpho/commands", "version": "0.1.0", "description": "Command registry (loader by folder, aliases, duplicate/typo warnings), prefix parsing, a dispatcher with owner/admin guards and hooks, and a per-person antiflood.", "main": "index.js", "license": "MIT" }

package/packages/context/README.md

@@ -0,0 +1,100 @@
+# morpho-socket/context
+
+The **`g`** every command receives: one object with everything about the current message. One door per topic, the same mould everywhere, and no exceptions thrown for *expected* reasons (no permission, person not in the group…).
+
+```js
+const { createContext } = require("morpho-socket/context")
+const { createIdentity } = require("morpho-socket/jid")
+
+const contexts = createContext({
+  identity: createIdentity({ store }),            // required
+  media, interactive,                             // optional: g.download*, buttons/lists
+  getGroupMeta: (sock, jid) => groups.get(jid),   // default: sock.groupMetadata(jid)
+  isOwner: g => g.user.phone === "5511999999999", // default: only the bot's own device
+  protect: (g, person) => person.number === OWNER,// extra untouchables for g.kick / g.demote
+  prefix: "!",                                    // default "/"
+  prefixFor: (g, jid) => prefixOf(jid),           // per-group prefix, overrides `prefix`
+  names: { owner: "Owner", user: "Someone" },     // g.user.name: `owner` when the bot's own device sends, `user` when there is no push name
+  extend: {                                       // YOUR bot's own getters and methods
+    get vip() { return this.client?.vip },
+    shout(text) { return this.reply(text.toUpperCase()) },
+  },
+})
+
+const g = await contexts.build({ sock, msg, clientId, anything: "else" })   // extra props are copied onto g
+```
+
+`build()` resolves the sender once and never throws.
+
+## The message and who sent it
+
+| | |
+|---|---|
+| message | `g.text` `g.type` `g.id` `g.chatId` `g.isGroup` `g.isPrivate` `g.isFromMe` `g.timestamp` `g.quoted` `g.mentions` `g.is("image", …)` |
+| command | `g.command` → `{ prefix, name, args, argText }` or `null` · shortcuts `g.args` `g.argText` `g.prefix` |
+| sender | `g.user` → `{ jid, lid, phone, hasPhone, number, formatted, source, name }` — `number` is never empty (the phone, or the LID digits): it is the key to use in your database |
+| permissions | `g.isOwner` · `await g.isAdmin()` · `await g.isBotAdmin()` |
+| raw | `g.msg` `g.sock` `g.clientId` `g.parsed` (the [`message`](../message) object) `g.identity` |
+
+A tap on one of **your** buttons becomes `g.text` (e.g. `"menu games"`). A tap on another bot's button is ignored.
+
+## People
+
+`await g.who(x?)` returns a **Person** or `null`: `{ jid, lid, phone, number, admin, superadmin, bot }`.
+
+With no argument: the mentioned person, or the author of the replied-to message. With an argument: a number, a JID, a `@lid`, or another Person.
+
+## Groups
+
+`await g.group()` → `{ id, name, description, owner, size, announce, locked, approval, createdAt }` · `await g.members()` · `await g.admins()`
+
+**Actions** all share one mould. They never throw; they return `{ ok, action, reason?, jid?, number? }`. Several at once: `g.kick([a, b])` → `{ ok, results }`, **one** WhatsApp call. Morpho never writes text for the user — your bot translates `reason`.
+
+```js
+const r = await g.kick()                          // or g.kick("5511999999999") / jid / Person
+if (!r.ok) return g.reply(messages[r.reason] ?? messages.failed)
+```
+
+| | |
+|---|---|
+| people | `kick` `promote` `demote` `add(number)` `approve` `reject` |
+| tag everyone | `tagAll(text, { quote, admins, bot })` — hidden mention: nobody sees a list of numbers, everybody is notified → `{ ok, action, count, sent }` |
+| group | `close()` `open()` `lock()` `unlock()` `rename(text)` `setDescription(text)` `leave()` |
+| invite link | `link()` · `revokeLink()` → `{ code, url }` |
+| message | `delete()` removes the replied-to message (or the command itself) · `delete("command")` · `delete(sentMessage)` |
+
+Safe by default: `kick` and `demote` don't touch the bot, the group creator or admins (`kick(x, { admins: true })` allows admins). `add` returns `needs-invite` (with `invite`) when the person's privacy settings require an invite link.
+
+**`reason` codes** (also exported as `GROUP_REASONS`): `not-group` · `bot-not-admin` · `no-target` · `invalid-user` · `not-in-group` · `already-in-group` · `already-admin` · `not-admin` · `target-is-bot` · `target-is-creator` · `target-is-admin` · `protected` · `not-allowed` · `needs-invite` · `not-on-whatsapp` · `recently-left` · `invalid-text` · `rate-limited` · `failed`
+
+## Sending: one door
+
+```js
+await g.reply("hi")                                          // quotes the command, keeps mentions
+await g.reply({ image: buf, caption: "look" })               // image | video | gif | sticker | voice | audio | document
+await g.reply({ body: "Pick one", buttons, fallback: "plain text" })   // buttons/list; falls back to text on failure
+await g.send(jid, "hi")                                      // another chat (quotes only with { quote: true })
+await g.reply(`congrats ${await g.at(person)}!`)             // g.at() writes "@id" AND registers the mention
+
+const sent = await g.reply("calculating…")
+await g.edit(sent, "done!");  await g.delete(sent)
+await g.react("🎉");  await g.poll("Pizza?", ["yes", "no"])
+```
+
+Media sources: `Buffer` · `"https://…"` · `"/path/to/file"` · `{ url }` (sticker and voice need a Buffer or a file). Options (second argument, or inside the object): `mentions` (anything `g.at` understands), `quote: false | true | msg`, `mimetype` / `fileName`.
+
+**Read more:** `g.readMore` is a string; put it between two parts of a text and WhatsApp folds the second part behind "Read more…": ``await g.reply(`Title${g.readMore}Long text`)``.
+
+Everything returns the sent message (with `.key`). If quoting fails (e.g. the command came from a button tap) it sends without the quote; if the media fails and there is a caption, it sends the caption. **A command is never left mute.**
+
+## Incoming media
+
+`g.media()` looks without downloading (`type`, `seconds`, `size`…) · `g.hasMedia` · `await g.download()` → `Buffer | null` · `await g.downloadInfo()` → `{ buffer, type, mimetype, … }`.
+
+The **replied-to** media wins over the message's own. Options: `{ types, max, quoted: "prefer" | "only" | "never", viewOnce }` — view-once media is only returned with `viewOnce: true`, so nobody can reveal it by accident. Errors carry `.code` (`MEDIA_TOO_LARGE`, `MEDIA_EXPIRED`…). Caching, retries and expired links are [`media`](../media)'s job.
+
+## Extending `g`
+
+`extend` takes an object whose **getters stay getters**; inside them `this` is the `g`. That is where your rules live — plans, per-group settings, helpers — while the generic parts stay in Morpho.
+
+Also exported: `participantIds`, `isAdminRole`, `GROUP_REASONS`, `digits`.

package/packages/context/group.js

@@ -0,0 +1,269 @@
+// @morpho/context/group — group actions on the "g":  g.kick(user), g.promote(user), g.close() ...
+//
+// One mould for everything:
+//   const r = await g.kick(@mention | "5511999999999" | jid | g.who() | nothing)   // nothing = mentioned / replied person
+//   r -> { ok: true,  action, jid, number }
+//        { ok: false, action, reason, jid?, number?, error? }          // it NEVER throws
+//   g.kick([a, b, c]) -> { ok, action, results: [r, r, r] }              // several at once, one WhatsApp call
+//
+// `reason` is a short stable code (see REASONS) — the bot decides what to say; Morpho never writes user-facing text.
+// Safe by default: admins, the group creator and the bot itself are protected (kick/demote). Pass { admins: true }
+// to allow kicking an admin. `createContext({ protect: (g, info) => bool })` adds your own untouchables (the bot owner...).
+const { normalize, digits } = require("../jid")
+const { userPart, participantIds, isAdminRole, botIds } = require("./participants")
+
+const REASONS = Object.freeze([
+  "not-group",          // used outside a group
+  "bot-not-admin",      // the bot needs to be admin for this
+  "no-target",          // nobody mentioned / replied to and nothing was passed
+  "invalid-user",       // could not understand who it is
+  "not-in-group",       // that person is not in the group
+  "already-in-group",   // add: already a member
+  "already-admin",      // promote: already admin
+  "not-admin",          // demote: is not admin
+  "target-is-bot",      // never acts on the bot itself
+  "target-is-creator",  // the group creator can't be touched
+  "target-is-admin",    // kick: admins are protected unless { admins: true }
+  "protected",          // your own protect() said no
+  "not-allowed",        // WhatsApp said 403
+  "needs-invite",       // add: privacy settings — send the invite link instead (result.invite)
+  "not-on-whatsapp",    // add: that number has no WhatsApp
+  "recently-left",      // add: left recently, can't be re-added yet
+  "invalid-text",       // rename/description: empty or too long
+  "rate-limited",       // WhatsApp asked us to slow down
+  "failed"              // anything else (result.error has the message)
+])
+
+const fail = (action, reason, extra) => ({ ok: false, action, reason, ...extra })
+const success = (action, extra) => ({ ok: true, action, ...extra })
+
+function reasonFromError(e) {
+  const code = Number(e?.output?.statusCode ?? e?.data ?? e?.status ?? e?.statusCode)
+  const msg = String(e?.message || e || "")
+  if (/not-authorized/i.test(msg) || code === 401) return "bot-not-admin"
+  if (/forbidden/i.test(msg) || code === 403) return "not-allowed"
+  if (/item-not-found/i.test(msg) || code === 404) return "not-in-group"
+  if (/rate-overlimit/i.test(msg) || code === 429) return "rate-limited"
+  return "failed"
+}
+
+// per-participant status of groupParticipantsUpdate ("200", "403"...) -> reason (null = ok)
+function reasonFromStatus(status, op) {
+  const s = String(status ?? "200")
+  if (s === "200") return null
+  if (s === "403") return op === "add" ? "needs-invite" : "not-allowed"
+  if (s === "404") return op === "add" ? "not-on-whatsapp" : "not-in-group"
+  if (s === "408") return "recently-left"
+  if (s === "409") return "already-in-group"
+  if (s === "401") return "not-allowed"
+  if (s === "429") return "rate-limited"
+  return "failed"
+}
+
+function createGroupActions({ identity, protect } = {}) {
+  async function guard(g, action, needBotAdmin = true) {
+    if (!g.isGroup) return fail(action, "not-group")
+    try { if (needBotAdmin && !(await g.isBotAdmin())) return fail(action, "bot-not-admin") }
+    catch (e) { return fail(action, "failed", { error: e?.message }) }
+    return null
+  }
+
+  // Person: { jid, lid, phone, number, admin, superadmin, bot }.  number never empty (phone, else the LID digits).
+  // resolve=false skips the (possible) identity lookup, for listing many members cheaply.
+  async function describe(g, p, resolve = true) {
+    const me = botIds(g.sock)
+    const id = String(p.id)
+    const lid = p.lid || (id.endsWith("@lid") ? id : null)
+    let phone = p.phoneNumber ? userPart(p.phoneNumber) : (id.endsWith("@s.whatsapp.net") ? userPart(id) : null)
+    if (!phone && resolve) { try { phone = (await identity.resolveJid(p.id, { sock: g.sock, clientId: g.clientId, group: g.chatId }))?.number || null } catch {} }
+    return { jid: p.id, lid, phone, number: phone || userPart(id), admin: isAdminRole(p), superadmin: p.admin === "superadmin", bot: participantIds(p).some(x => me.includes(x)) }
+  }
+
+  // one call for one or many; resolve(x) -> { error, jid?, number? } | { jid, number?, info? }; check(info, opts) -> reason | null
+  async function run(g, action, op, input, opts, { resolve, check, call }) {
+    const many = Array.isArray(input)
+    const list = many ? input : [input]
+    const blocked = await guard(g, action)
+    const out = new Array(list.length)
+    if (blocked) { list.forEach((_, i) => { out[i] = blocked }); return many ? { ok: false, action, results: out } : blocked }
+
+    const valid = []
+    for (let i = 0; i < list.length; i++) {
+      let r
+      try { r = await resolve(list[i]) } catch (e) { r = { error: "failed", message: e?.message } }
+      if (r.error) { out[i] = fail(action, r.error, { jid: r.jid, number: r.number, error: r.message }); continue }
+      const why = check ? await check(r.info, opts) : null
+      if (why) { out[i] = fail(action, why, { jid: r.jid, number: r.number }); continue }
+      valid.push({ i, jid: r.jid, number: r.number })
+    }
+
+    if (valid.length) {
+      let res = null, thrown = null
+      try { res = await call(valid.map(v => v.jid)) } catch (e) { thrown = e }
+      const byJid = new Map((Array.isArray(res) ? res : []).map(x => [normalize(x?.jid), x]))
+      for (const v of valid) {
+        if (thrown) { out[v.i] = fail(action, reasonFromError(thrown), { jid: v.jid, number: v.number, error: thrown?.message }); continue }
+        const st = byJid.get(normalize(v.jid))
+        const why = reasonFromStatus(st?.status, op)
+        out[v.i] = why ? fail(action, why, { jid: v.jid, number: v.number, ...(why === "needs-invite" && st?.content ? { invite: st.content } : {}) })
+                       : success(action, { jid: v.jid, number: v.number })
+      }
+    }
+    return many ? { ok: out.every(r => r.ok), action, results: out } : out[0]
+  }
+
+  // single-shot setting/info calls
+  async function simple(g, action, { needBotAdmin = true, call, map }) {
+    const blocked = await guard(g, action, needBotAdmin)
+    if (blocked) return blocked
+    try { const v = await call(); return success(action, map ? map(v) : {}) }
+    catch (e) { return fail(action, reasonFromError(e), { error: e?.message }) }
+  }
+
+  const inGroup = async (g, x) => {            // resolveUser wrapper -> run()'s resolve shape
+    const r = await g.resolveUser(x)
+    return r.error ? { error: r.error, jid: r.jid, number: r.number } : { jid: r.info.jid, number: r.info.number, info: r.info }
+  }
+  const outsider = async x => {               // for add/approve/reject: people who are NOT members yet
+    const raw = typeof x === "string" ? x : (x?.id || x?.jid || x?.number || x?.pn)
+    const d = typeof raw === "string" && !raw.endsWith("@lid") ? digits(raw) : null
+    if (d) return { jid: `${d}@s.whatsapp.net`, number: d }
+    if (typeof raw === "string" && raw.endsWith("@lid")) return { jid: normalize(raw), number: null }
+    return { error: "invalid-user" }
+  }
+  const protectCheck = async (g, info) => (protect && await protect(g, info)) ? "protected" : null
+
+  return {
+    // -> { info } | { error, jid?, number? }.   info: { id, jid, number, admin, superadmin, bot }
+    async resolveUser(input) {
+      if (input === undefined || input === null) input = this.mentions[0] || this.parsed.context?.participant   // mentioned, else the replied person
+      if (!input) return { error: "no-target" }
+      const raw = typeof input === "string" ? input : (input.jid || input.lid || (input.phone && `${input.phone}@s.whatsapp.net`) || input.number)
+      if (typeof raw !== "string") return { error: "invalid-user" }
+      const want = raw.includes("@") ? normalize(raw) : (digits(raw) ? `${digits(raw)}@s.whatsapp.net` : null)
+      if (!want) return { error: "invalid-user" }
+      const meta = await this.groupMeta()
+      const p = meta?.participants?.find(p => participantIds(p).includes(want))
+      if (!p) return { error: "not-in-group", jid: want, number: digits(want) }
+      return { info: await describe(this, p) }
+    },
+    // the Person (see above) or null: g.who() = mentioned/replied; g.who("5511...") / g.who(jid) / g.who(person)
+    async who(input) { return (await this.resolveUser(input)).info || null },
+
+    // ----- group info -----
+    async group() {
+      if (!this.isGroup) return null
+      const m = await this.groupMeta()
+      if (!m) return null
+      return { id: this.chatId, name: m.subject || "", description: m.desc || null, owner: m.owner || null, size: m.participants?.length ?? m.size ?? 0,
+        announce: !!m.announce, locked: !!m.restrict, approval: !!m.joinApprovalMode, createdAt: m.creation ? m.creation * 1000 : null }
+    },
+    async members() { return Promise.all(((await this.groupMeta())?.participants || []).map(p => describe(this, p, false))) },
+    async admins() { return (await this.members()).filter(m => m.admin) },
+
+    // ----- tag everyone (hidden: the text shows no @numbers, but everybody is notified) -----
+    // await g.tagAll("Attention, everyone!")                  // quotes the command by default
+    // await g.tagAll("Hi", { quote: false, admins: true })    // admins: only tag the admins
+    // -> { ok: true, action, count, sent } | { ok: false, action, reason }
+    async tagAll(text, opts = {}) {
+      const blocked = await guard(this, "tagAll", false)
+      if (blocked) return blocked
+      const t = String(text ?? "")
+      if (!t.trim()) return fail("tagAll", "invalid-text")
+      try {
+        const meta = await this.groupMeta()
+        const me = botIds(this.sock)
+        const jids = (meta?.participants || [])
+          .filter(p => (!opts.admins || isAdminRole(p)) && !(opts.bot === false && participantIds(p).some(x => me.includes(x))))
+          .map(p => p.id)
+        const content = { text: t, mentions: jids }
+        const quoted = opts.quote === false ? null : (opts.quote && opts.quote !== true ? opts.quote : this.msg)
+        let sent
+        try { sent = await this.sock.sendMessage(this.chatId, content, quoted ? { quoted } : undefined) }
+        catch (e) { if (!quoted) throw e; sent = await this.sock.sendMessage(this.chatId, content) }   // quote failed (button tap...)? send loose
+        return success("tagAll", { count: jids.length, sent })
+      } catch (e) { return fail("tagAll", reasonFromError(e), { error: e?.message }) }
+    },
+
+    kick(user, opts = {}) {
+      return run(this, "kick", "remove", user, opts, {
+        resolve: x => inGroup(this, x),
+        check: async (info, o) => info.bot ? "target-is-bot" : info.superadmin ? "target-is-creator"
+          : (info.admin && !o.admins) ? "target-is-admin" : protectCheck(this, info),
+        call: jids => this.sock.groupParticipantsUpdate(this.chatId, jids, "remove")
+      })
+    },
+    promote(user, opts = {}) {
+      return run(this, "promote", "promote", user, opts, {
+        resolve: x => inGroup(this, x),
+        check: info => info.bot ? "target-is-bot" : info.admin ? "already-admin" : null,
+        call: jids => this.sock.groupParticipantsUpdate(this.chatId, jids, "promote")
+      })
+    },
+    demote(user, opts = {}) {
+      return run(this, "demote", "demote", user, opts, {
+        resolve: x => inGroup(this, x),
+        check: async info => info.bot ? "target-is-bot" : info.superadmin ? "target-is-creator" : !info.admin ? "not-admin" : protectCheck(this, info),
+        call: jids => this.sock.groupParticipantsUpdate(this.chatId, jids, "demote")
+      })
+    },
+    // add("5511999999999") / add([..]) — numbers or phone JIDs
+    add(number, opts = {}) {
+      return run(this, "add", "add", number, opts, {
+        resolve: outsider,
+                call: jids => this.sock.groupParticipantsUpdate(this.chatId, jids, "add")
+      })
+    },
+    // join requests (groups with approval)
+    approve(user, opts = {}) {
+      return run(this, "approve", "approve", user, opts, { resolve: outsider, call: jids => this.sock.groupRequestParticipantsUpdate(this.chatId, jids, "approve") })
+    },
+    reject(user, opts = {}) {
+      return run(this, "reject", "reject", user, opts, { resolve: outsider, call: jids => this.sock.groupRequestParticipantsUpdate(this.chatId, jids, "reject") })
+    },
+
+    // ----- group settings -----
+    rename(subject) {
+      const t = String(subject ?? "").trim()
+      if (!t || t.length > 100) return Promise.resolve(fail("rename", this.isGroup ? "invalid-text" : "not-group"))
+      return simple(this, "rename", { needBotAdmin: false, call: () => this.sock.groupUpdateSubject(this.chatId, t) })
+    },
+    setDescription(text) {
+      const t = String(text ?? "")
+      if (t.length > 2048) return Promise.resolve(fail("setDescription", this.isGroup ? "invalid-text" : "not-group"))
+      return simple(this, "setDescription", { needBotAdmin: false, call: () => this.sock.groupUpdateDescription(this.chatId, t || undefined) })
+    },
+    close() { return simple(this, "close", { call: () => this.sock.groupSettingUpdate(this.chatId, "announcement") }) },       // only admins talk
+    open() { return simple(this, "open", { call: () => this.sock.groupSettingUpdate(this.chatId, "not_announcement") }) },     // everyone talks
+    lock() { return simple(this, "lock", { call: () => this.sock.groupSettingUpdate(this.chatId, "locked") }) },               // only admins edit group info
+    unlock() { return simple(this, "unlock", { call: () => this.sock.groupSettingUpdate(this.chatId, "unlocked") }) },
+
+    // ----- invite link -----
+    link() { return simple(this, "link", { call: () => this.sock.groupInviteCode(this.chatId), map: code => ({ code, url: `https://chat.whatsapp.com/${code}` }) }) },
+    revokeLink() { return simple(this, "revokeLink", { call: () => this.sock.groupRevokeInvite(this.chatId), map: code => ({ code, url: `https://chat.whatsapp.com/${code}` }) }) },
+    leave() { return simple(this, "leave", { needBotAdmin: false, call: () => this.sock.groupLeave(this.chatId) }) },
+
+    // ----- delete a message for everyone -----
+    // g.delete()            -> the replied message (or the command itself if nothing was replied to)
+    // g.delete("command")   -> the command message
+    // g.delete(sentResult)  -> a message the bot sent (its { key }) or any Baileys key
+    async delete(target) {
+      let key
+      if (target && typeof target === "object") key = target.key || target
+      else if (target === "command" || !this.quoted) key = this.msg?.key
+      else {
+        const c = this.parsed.context || {}
+        const who = c.participant || null
+        key = { remoteJid: this.chatId, id: c.stanzaId, fromMe: !!who && botIds(this.sock).includes(normalize(who)), participant: who || undefined }
+      }
+      if (!key?.id) return fail("delete", "invalid-user")
+      const own = !!key.fromMe
+      const blocked = await guard(this, "delete", this.isGroup && !own)
+      if (blocked && blocked.reason !== "not-group") return blocked
+      try { await this.sock.sendMessage(this.chatId, { delete: { ...key, remoteJid: key.remoteJid || this.chatId } }); return success("delete", { key }) }
+      catch (e) { return fail("delete", reasonFromError(e), { error: e?.message }) }
+    }
+  }
+}
+
+module.exports = { createGroupActions, REASONS, reasonFromError, reasonFromStatus }