morpho-socket 0.0.0-stage → 0.2.0

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,97 @@
+# 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` |
+| 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`.
+
+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,245 @@
+// @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) },
+
+    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 }

package/packages/context/index.js

@@ -0,0 +1,132 @@
+// @morpho/context — the "g" every command receives: ONE object with everything about the current message.
+//
+//   const { createContext } = require("@morpho/context")
+//   const contexts = createContext({
+//     identity,                          // createIdentity() from @morpho/jid                (required)
+//     media, interactive,                // createMedia() / createInteractive()              (optional: g.download*, buttons)
+//     getGroupMeta: (sock, jid) => groups.get(jid),   // default sock.groupMetadata(jid) (use @morpho/groups for cache)
+//     isOwner: g => g.user.phone === "5511…",         // default: only the bot's own device
+//     protect: (g, person) => boolean,   // extra untouchables for g.kick / g.demote (the bot owner...)
+//     prefixFor: (g, jid) => "!", prefix: "/",
+//     names: { owner: "Dono", user: "Alguém" },
+//     extend: { get vip() { return this.client?.vip }, myHelper() {} }   // the bot's own getters/methods
+//   })
+//   const g = await contexts.build({ sock, msg, clientId, ...anythingElse })   // extra props are copied onto g
+//
+// The shape of g (details: README):
+//   message   g.text g.type g.id g.isGroup g.isPrivate g.chatId g.quoted g.mentions g.command g.args g.argText g.prefix
+//   sender    g.user { jid lid phone number name ... }  g.isOwner  await g.isAdmin()  await g.isBotAdmin()
+//   people    await g.who(x?) -> Person | null        Person = { jid, lid, phone, number, admin, superadmin, bot }
+//   group     await g.group()  g.members()  g.admins()  g.kick  g.promote  g.demote  g.add  g.close  g.open  g.link ...
+//   send      g.reply  g.send  g.at  g.react  g.edit  g.delete  g.poll
+//   media     g.media()  g.hasMedia  await g.download()  await g.downloadInfo()
+const { parse } = require("../message")
+const { createGroupActions, REASONS } = require("./group")
+const { createSend } = require("./send")
+const { userPart, participantIds, isAdminRole, botIds } = require("./participants")
+const { normalize, digits } = require("../jid")
+
+function createContext({ identity, media, interactive, getGroupMeta, isOwner, protect, prefixFor, prefix = "/", names = {}, interactiveEnabled = () => true, extend = {} } = {}) {
+  if (!identity) throw new Error("createContext: 'identity' is required (createIdentity from @morpho/jid)")
+  const fetchMeta = getGroupMeta || ((sock, jid) => sock.groupMetadata(jid))
+  const nameOf = { owner: "Owner", user: "User", ...names }
+
+  const proto = {
+    msg: null, sock: null, identity: null, clientId: null, user: null,
+
+    // ----- the message -----
+    get parsed() { return parse(this.msg) },
+    get id() { return this.msg?.key?.id || null },
+    get type() { return this.parsed.type },
+    is(...types) { return types.includes(this.parsed.type) },
+    get chatId() { return this.msg?.key?.remoteJid || null },
+    get isGroup() { return this.parsed.isGroup },
+    get isPrivate() { return !this.parsed.isGroup && !this.parsed.isStatus && !this.parsed.isNewsletter },
+    get isFromMe() { return this.parsed.fromMe },
+    get timestamp() { return this.parsed.timestamp },
+    get mentions() { return this.parsed.mentions },
+    get quoted() { return this.parsed.quoted },              // parsed quoted message (text, media, sender...) or null
+    get readMore() { return "\u200E".repeat(4000) },
+
+    // text/caption; a tap on one of OUR buttons/list rows counts as the command it carries (e.g. "/menu games")
+    get text() { return this.parsed.text || this.interactiveReply || null },
+    get interactiveReply() { return interactive ? interactive.parseSelection(this.msg, { sock: this.sock }) : null },
+
+    // the group's prefix, and the command split: "!ban @x motivo" -> { prefix, name: "ban", args: ["@x","motivo"], argText: "@x motivo" }
+    get prefix() { return prefixFor ? prefixFor(this, this.chatId) : prefix },
+    get command() {
+      const t = this.text, p = this.prefix
+      if (!t || !p || !t.startsWith(p)) return null
+      const rest = t.slice(p.length).trim()
+      if (!rest) return null
+      const [name, ...args] = rest.split(/ +/)
+      return { prefix: p, name: name.toLowerCase(), args, argText: rest.slice(name.length).trim() }
+    },
+    get args() { return this.command?.args || [] },
+    get argText() { return this.command?.argText || "" },
+
+    // ----- permissions -----
+    get isOwner() { return isOwner ? !!isOwner(this) : this.isFromMe },
+    async groupMeta() { return this.isGroup ? fetchMeta(this.sock, this.chatId) : null },
+    async isAdmin() {
+      if (!this.isGroup) return false
+      const meta = await this.groupMeta()
+      if (!meta?.participants) return false
+      const mine = [this.identity?.jid, this.identity?.lid, this.identity?.pn].filter(Boolean).map(normalize).filter(Boolean)
+      if (!mine.length) return false
+      return isAdminRole(meta.participants.find(p => participantIds(p).some(x => mine.includes(x))))
+    },
+    async isBotAdmin() {
+      if (!this.isGroup) return false
+      const meta = await this.groupMeta()
+      if (!meta?.participants) return false
+      const me = botIds(this.sock)
+      return isAdminRole(meta.participants.find(p => participantIds(p).some(x => me.includes(x))))
+    },
+
+    // ----- media (incoming) -----
+    // opts: { types: ["image","video","audio"], max (bytes), quoted: "prefer"|"only"|"never", viewOnce: false }
+    // The QUOTED media wins over the message's own. View-once only with viewOnce: true (else anyone could reveal it with /s).
+    media({ types = ["image", "video", "audio"], quoted, viewOnce = false } = {}) {          // look only (type, seconds, size...) -> info | null
+      if (!media) throw new Error("g.media: pass 'media' to createContext")
+      if (!this.msg?.message) return null
+      const found = media.find(this.msg, { types, quoted })
+      return !found || (found.viewOnce && !viewOnce) ? null : found
+    },
+    get hasMedia() { try { return !!this.media() } catch { return false } },
+    downloadFound(found, { max } = {}) { return media.downloadFound(found, { sock: this.sock, max }) },
+    async downloadInfo(opts) { const f = this.media(opts); return f ? this.downloadFound(f, { max: opts?.max }) : null },   // { buffer, type, mimetype, ... } | null
+    async download(opts) { return (await this.downloadInfo(opts))?.buffer ?? null },                                       // Buffer | null. Errors carry .code (MEDIA_TOO_LARGE, MEDIA_EXPIRED...)
+  }
+
+  // sending (reply/send/at/react/edit/poll) and group actions (kick/promote/.../who/group/members)
+  const mix = o => Object.defineProperties(proto, Object.getOwnPropertyDescriptors(o))
+  mix(createSend({ interactive, interactiveEnabled }))
+  mix(createGroupActions({ identity, protect }))
+  // the bot's own getters/methods (descriptors are copied so getters stay getters)
+  mix(extend)
+
+  // props: { sock, msg, clientId, ...anything }. Resolves the sender ONCE; never throws.
+  async function build({ sock, msg, clientId, ...rest }) {
+    const g = Object.create(proto)
+    Object.assign(g, rest)
+    g.msg = msg; g.sock = sock; g.clientId = clientId
+    const id = g.identity = await identity.resolveSender(msg, sock, clientId)
+    const lid = id?.lid || null, jid = id?.jid || null
+    g.user = Object.freeze({
+      jid, lid,
+      phone: id?.number || null,                                   // the real phone number, or null (LID not resolved yet)
+      hasPhone: !!id?.number,
+      number: id?.number || (lid ? userPart(lid) : null) || (jid ? userPart(jid) : null),   // never empty when there is a sender: the key to use in your database
+      formatted: id?.formatted || null,
+      source: id?.source || null,
+      name: g.isFromMe ? nameOf.owner : (msg?.pushName || nameOf.user)
+    })
+    media?.bind(msg, sock) // if the link expires, @morpho/media asks the phone to re-send through this sock
+    return g
+  }
+
+  return { proto, build }
+}
+
+module.exports = { createContext, participantIds, isAdminRole, GROUP_REASONS: REASONS, digits }

package/packages/context/package.json

@@ -0,0 +1 @@
+{ "name": "@morpho/context", "version": "0.2.0", "description": "The per-message context ('g') every command receives: who sent it (LID resolved to a number), text, mentions, quoted message, permissions, target/mention helpers, reply/send helpers and media download. Built on @morpho/message, jid, groups, reply, media and interactive.", "main": "index.js", "dependencies": { "@morpho/message": "file:../message", "@morpho/reply": "file:../reply", "@morpho/jid": "file:../jid" }, "license": "MIT" }