morpho-socket 0.0.0-stage → 0.2.0

package/packages/context/participants.js

@@ -0,0 +1,12 @@
+// @morpho/context — helpers shared by index.js (the "g") and group.js (group actions).
+// Everything here is pure: no sock, no I/O.
+const { normalize } = require("../jid")
+
+const userPart = j => String(j).split("@")[0].split(":")[0]
+const cleanJid = j => (j ? j.replace(/:\d+(?=@)/, "") : null)
+// every id a group participant can have (Baileys 7: id, lid, phoneNumber), normalized
+const participantIds = p => [p?.id, p?.lid, p?.phoneNumber, p?.jid].filter(x => typeof x === "string").map(normalize).filter(Boolean)
+const isAdminRole = p => p?.admin === "admin" || p?.admin === "superadmin"
+const botIds = sock => [sock?.user?.id, sock?.user?.lid].filter(Boolean).map(normalize).filter(Boolean)
+
+module.exports = { userPart, cleanJid, participantIds, isAdminRole, botIds }

package/packages/context/send.js

@@ -0,0 +1,127 @@
+// @morpho/context/send — everything the "g" SENDS, through one door.
+//
+//   await g.reply("oi")                                   // quotes the command, keeps mentions
+//   await g.reply({ image: buf, caption: "olha" })        // image | video | gif | sticker | voice | audio | document
+//   await g.reply({ body: "Escolha", buttons: [...], fallback: "texto se não der" })   // buttons/list (needs @morpho/interactive)
+//   await g.send(jid, "oi")                               // any other chat (does not quote unless { quote: true })
+//   await g.reply(`parabéns ${await g.at(person)}!`)      // g.at() writes "@123" AND remembers the mention: it just works
+//   const sent = await g.reply("calculando...");  await g.edit(sent, "pronto!");  await g.delete(sent)
+//
+// Every method returns the sent WhatsApp message (with .key). Options (2nd arg, or inside the content object):
+//   mentions: [anything g.at() understands]   quote: false | true | someMsg   mimetype / fileName (document, audio)
+// Sources (image, video, gif, sticker, voice, audio, document): Buffer | "https://..." | "/path/file" | { url }.
+const fs = require("fs")
+const reply = require("../reply")
+const { normalize, digits } = require("../jid")
+const { userPart, participantIds, cleanJid } = require("./participants")
+
+const MEDIA_KINDS = ["image", "video", "gif", "sticker", "voice", "audio", "document"]
+
+function source(x) {
+  if (Buffer.isBuffer(x)) return x
+  if (typeof x === "string") return /^https?:\/\//i.test(x) ? { url: x } : fs.readFileSync(x)
+  if (x && typeof x === "object" && x.url) return x
+  throw new Error("invalid media source (use a Buffer, a path, a URL or { url })")
+}
+const needBuffer = (x, what) => { const s = source(x); if (!Buffer.isBuffer(s)) throw new Error(`${what}: needs a Buffer or a local file (not a URL)`); return s }
+
+function createSend({ interactive, interactiveEnabled = () => true } = {}) {
+  // anything -> the participant's NATIVE jid (@lid in LID groups): the one WhatsApp swaps for the contact's name
+  async function nativeJid(g, input) {
+    if (input === undefined || input === null) input = g.user
+    if (typeof input === "object") input = input.jid || input.lid || (input.phone && `${input.phone}@s.whatsapp.net`) || input.number
+    if (typeof input !== "string") return null
+    const jid = input.includes("@") ? cleanJid(input) : (digits(input) ? `${digits(input)}@s.whatsapp.net` : null)
+    if (!jid) return null
+    if (!g.isGroup) return jid
+    const meta = await g.groupMeta().catch(() => null)
+    const p = meta?.participants?.find(p => participantIds(p).includes(normalize(jid)))
+    return p?.id || jid
+  }
+
+  async function collect(g, explicit = [], text = "") {
+    const out = new Set()
+    for (const m of explicit) { const j = await nativeJid(g, m); if (j) out.add(j) }
+    const tags = g._tags
+    if (tags?.size && text) for (const m of String(text).matchAll(/@(\d+)/g)) if (tags.has(m[1])) out.add(tags.get(m[1]))
+    return [...out]
+  }
+
+  // content -> { kind, text, body... }
+  function classify(c) {
+    if (typeof c === "string" || typeof c === "number") return { kind: "text", text: String(c) }
+    if (!c || typeof c !== "object") throw new Error("reply/send: content must be a string or an object")
+    if (c.buttons) return { kind: "interactive", text: c.fallback ?? c.body ?? c.text ?? "" }
+    for (const k of MEDIA_KINDS) if (c[k] !== undefined && c[k] !== null) return { kind: k, text: c.caption ?? c.text ?? "" }
+    return { kind: "text", text: c.text ?? "" }
+  }
+
+  async function deliver(g, to, c, defaults = {}) {
+    const x = classify(c)
+    const o = typeof c === "object" ? c : {}
+    const wantQuote = o.quote ?? defaults.quote
+    const quoted = wantQuote && wantQuote !== true ? wantQuote : (wantQuote && to === g.chatId ? g.msg : null)
+    const mentions = await collect(g, [...(defaults.mentions || []), ...(o.mentions || [])], x.text + " " + (o.body || ""))
+    const sock = g.sock
+    const plain = () => sock.sendMessage(to, { text: x.text, mentions })
+    const sendText = async () => {
+      if (!quoted) return plain()
+      try { return await reply.reply(sock, to, quoted, x.text, { mentions }) } catch { return plain() }   // quoting failed (e.g. button tap)? send loose
+    }
+
+    switch (x.kind) {
+      case "text": return sendText()
+
+      case "interactive": {
+        if (interactive && interactiveEnabled()) {
+          try { return await interactive.send(sock, to, { body: o.body ?? o.text, footer: o.footer || "", buttons: o.buttons, mentions, image: o.image, imageId: o.imageId, msg: quoted || undefined }) }
+          catch (e) { console.log("[morpho] interactive failed, using text:", e?.message) }
+        }
+        return sendText()                                   // the command is never mute
+      }
+
+      case "image": case "video": case "gif": case "document": {
+        const caption = o.caption ?? o.text ?? ""
+        const content = x.kind === "gif" ? { video: source(o.gif), gifPlayback: true, caption, mentions }
+          : x.kind === "document" ? { document: source(o.document), mimetype: o.mimetype || "application/octet-stream", fileName: o.fileName || "file", caption, mentions }
+          : { [x.kind]: source(o[x.kind]), caption, mentions }
+        const onError = e => console.log(`[morpho] ${x.kind} send failed:`, e?.message)
+        if (quoted) return reply.replyMedia(sock, to, quoted, content, { text: caption, mentions, onError })
+        try { return await sock.sendMessage(to, content) }
+        catch (e) { onError(e); if (caption) return plain(); throw e }
+      }
+
+      case "sticker": return reply.sendSticker(sock, to, needBuffer(o.sticker, "sticker"), { quoted: quoted || undefined })
+      case "voice": return reply.sendVoice(sock, to, needBuffer(o.voice, "voice"), { quoted: quoted || undefined })
+      case "audio": return sock.sendMessage(to, { audio: source(o.audio), mimetype: o.mimetype || "audio/mpeg" }, quoted ? { quoted } : undefined)
+    }
+  }
+
+  return {
+    // "@123" for a person (Person, number, jid, g.user; nothing = whoever sent the command) AND registers the mention.
+    async at(input) {
+      const jid = await nativeJid(this, input)
+      if (!jid) return ""
+      const id = userPart(jid)
+      ;(this._tags ||= new Map()).set(id, jid)
+      return "@" + id
+    },
+    mentionJid(input) { return nativeJid(this, input) },
+
+    reply(content, opts = {}) { return deliver(this, this.chatId, typeof content === "object" && content ? { ...opts, ...content } : { ...opts, text: content }, { quote: true, mentions: opts.mentions }) },
+    send(to, content, opts = {}) { return deliver(this, to, typeof content === "object" && content ? { ...opts, ...content } : { ...opts, text: content }, { quote: false, mentions: opts.mentions }) },
+
+    react(emoji, target) {
+      const key = target?.key || target || this.msg?.key
+      return this.sock.sendMessage(key?.remoteJid || this.chatId, { react: { text: emoji, key } })
+    },
+    // edit a message the bot sent (what reply/send returned)
+    edit(sent, text) {
+      const key = sent?.key || sent
+      return this.sock.sendMessage(key?.remoteJid || this.chatId, { text: String(text), edit: key })
+    },
+    poll(question, options = [], { to, multiple = false } = {}) { return reply.sendPoll(this.sock, to || this.chatId, question, options, { selectableCount: multiple ? options.length : 1 }) }
+  }
+}
+
+module.exports = { createSend }

package/packages/core/README.md

@@ -0,0 +1,50 @@
+# morpho-socket/core
+
+The session layer. Baileys defines the *format* of a session (credentials + Signal Protocol keys); Morpho only decides **where it is stored**.
+
+```js
+const { useMorphoAuthState } = require("morpho-socket/core")
+const { initAuthCreds, makeWASocket } = require("@whiskeysockets/baileys")
+const store = require("morpho-socket/store-sqlite").create({ path: "./data/sessions.sqlite" })
+
+const { state, saveCreds } = await useMorphoAuthState(store, "client-a", { initCreds: initAuthCreds })
+
+const sock = makeWASocket({ auth: state })
+sock.ev.on("creds.update", saveCreds)
+```
+
+`useMorphoAuthState(store, sessionId, { initCreds })` is a drop-in replacement for Baileys' `useMultiFileAuthState()`:
+
+- creates the credentials with `initCreds()` the first time and saves them;
+- keeps an in-memory cache in front of the store (Baileys reads and writes keys many times per message);
+- understands "delete this key" (`null`), which Baileys relies on.
+
+Morpho never generates cryptographic material: `initCreds` always comes from Baileys.
+
+> If you use [`pool`](../pool) you will never call this yourself — the pool does it for every session.
+
+## Writing your own backend
+
+A store is any object with these methods (duck typing works; extending `MorphoAuthStore` only gives you clear "not implemented" errors):
+
+```js
+readCreds(sessionId)             // -> saved object, or null if the session does not exist
+writeCreds(sessionId, creds)     // -> void
+readKeys(sessionId, type, ids)   // -> { [id]: data }   (ids with no saved value are left out)
+writeKeys(sessionId, writes)     // -> void   writes = { [type]: { [id]: data | null } }, null = delete
+deleteSession(sessionId)         // -> void   removes creds and every key of the session
+listSessions()                   // -> string[]
+```
+
+Optionally add `getLid(lid)` / `setLid(lid, number)` and [`jid`](../jid) will persist its LID → number map in your store.
+
+## Exports
+
+| | |
+|---|---|
+| `useMorphoAuthState(store, sessionId, { initCreds })` | → `{ state, saveCreds }` |
+| `MorphoAuthStore` | base class documenting the interface |
+| `encode(obj)` / `decode(text)` | JSON with `Buffer`/`Uint8Array` ⇄ base64, so keys survive serialization |
+| `loadBaileys()` | loads `@whiskeysockets/baileys` from **your** project (cwd / entry script folder) |
+
+See also: [`store-sqlite`](../store-sqlite), [`store-file`](../store-file).

package/packages/core/baileys.js

@@ -0,0 +1,25 @@
+// Loads modules from the BOT's project, not from where Morpho lives.
+//
+// Morpho is usually installed as a sibling folder (file:../morpho/packages/*). Node resolves a symlinked package from its
+// REAL path, so a plain require("pino") inside ../morpho/packages/pool looks in ../morpho/node_modules and misses the
+// bot's own node_modules. This tries the normal way first, then falls back to the bot's folder
+// (the process working directory and the entry script's folder).
+function loadFromBot(name) {
+  try { return require(name) } catch (e) { if (e.code !== "MODULE_NOT_FOUND" || !String(e.message).includes(`'${name}'`)) throw e }
+  const paths = [process.cwd(), require.main?.path].filter(Boolean)
+  try { return require(require.resolve(name, { paths })) }
+  catch { throw new Error(`${name} was not found. Install it in the bot's project (npm install ${name}). Looked in: ${paths.join(", ")}`) }
+}
+
+const loadBaileys = () => loadFromBot("@whiskeysockets/baileys")
+
+// Baileys logger: pino if the bot has it, else a silent stand-in with the same shape
+function silentLogger() {
+  try { return loadFromBot("pino")({ level: "silent" }) } catch { /* no pino: stub below */ }
+  const noop = () => {}
+  const l = { level: "silent", trace: noop, debug: noop, info: noop, warn: noop, error: noop, fatal: noop }
+  l.child = () => l
+  return l
+}
+
+module.exports = { loadFromBot, loadBaileys, silentLogger }

package/packages/core/codec.js

@@ -0,0 +1,17 @@
+// Serialização de creds/chaves para JSON. O Baileys guarda Buffer/Uint8Array (chaves do Signal
+// Protocol) dentro desses objetos, e JSON puro não suporta binário — vira um objeto vazio "{}".
+// Mesma ideia do BufferJSON interno do Baileys: binário vira { type: "Buffer", data: "<base64>" }
+// na hora de salvar, e volta a ser Buffer de verdade na hora de ler.
+function replacer(_key, value) {
+  if (value && (Buffer.isBuffer(value) || value instanceof Uint8Array || value?.type === "Buffer"))
+    return { type: "Buffer", data: Buffer.from(value.data ?? value).toString("base64") }
+  return value
+}
+function reviver(_key, value) {
+  if (value && typeof value === "object" && value.type === "Buffer" && typeof value.data === "string")
+    return Buffer.from(value.data, "base64")
+  return value
+}
+const encode = obj => JSON.stringify(obj, replacer)
+const decode = txt => (txt === undefined || txt === null ? null : JSON.parse(txt, reviver))
+module.exports = { encode, decode }

package/packages/core/index.js

@@ -0,0 +1,86 @@
+// @morpho/core
+//
+// O Baileys já define o FORMATO da sessão (creds + chaves do Signal Protocol); o Morpho só define
+// ONDE isso fica guardado. Um "MorphoAuthStore" é qualquer objeto com estes 5 métodos (veja store.js
+// para a classe-base com erro explicativo em quem esquecer de implementar algum).
+//
+//   readCreds(sessionId)              -> objeto salvo, ou null/undefined se não existe
+//   writeCreds(sessionId, creds)      -> void
+//   readKeys(sessionId, type, ids)    -> { [id]: dado }  (ids sem valor salvo ficam de fora do objeto)
+//   writeKeys(sessionId, writes)      -> void   (writes = { [type]: { [id]: dado|null } }; null = apagar)
+//   deleteSession(sessionId)          -> void   (apaga creds + todas as chaves da sessão)
+//
+// Quem usa (ex.: sessoes.js do Morvyn) troca só a linha do useMultiFileAuthState:
+//
+//   const { useMorphoAuthState } = require("@morpho/core")
+//   const { initAuthCreds } = require("@whiskeysockets/baileys")
+//   const { state, saveCreds } = await useMorphoAuthState(store, ctx.id, { initCreds: initAuthCreds })
+//   const sock = makeWaSocket({ auth: state, ... })
+//   sock.ev.on("creds.update", saveCreds)
+//
+// O Morpho NUNCA gera chave criptográfica: initCreds vem do próprio Baileys (initAuthCreds), porque
+// é geração de chave do Signal Protocol — isso é trabalho do Baileys, não do Morpho.
+
+async function useMorphoAuthState(store, sessionId, { initCreds } = {}) {
+  if (!store || typeof store.readCreds !== "function")
+    throw new Error("useMorphoAuthState: o primeiro argumento precisa ser um MorphoAuthStore (veja @morpho/core/store.js).")
+  if (!sessionId) throw new Error("useMorphoAuthState: sessionId é obrigatório.")
+
+  let creds = await store.readCreds(sessionId)
+  if (!creds) {
+    if (typeof initCreds !== "function")
+      throw new Error(
+        `useMorphoAuthState: nenhuma sessão salva para "${sessionId}" e nenhum initCreds foi passado. ` +
+        `Passe { initCreds: require("@whiskeysockets/baileys").initAuthCreds }.`
+      )
+    creds = initCreds()
+    await store.writeCreds(sessionId, creds)
+  }
+
+  // cache em memória: evita reler do backend uma chave que acabamos de escrever ou já lemos nesta sessão
+  // (o Baileys chama keys.get() e keys.set() MUITAS vezes por mensagem; isso poupa leitura de disco/rede)
+  const cache = new Map() // `${type}:${id}` -> dado | null (null = "sabemos que não existe")
+  const chave = (tipo, id) => `${tipo}:${id}`
+
+  const keys = {
+    async get(type, ids) {
+      const resultado = {}
+      const faltando = []
+      for (const id of ids) {
+        const k = chave(type, id)
+        if (cache.has(k)) { const v = cache.get(k); if (v !== null) resultado[id] = v }
+        else faltando.push(id)
+      }
+      if (faltando.length) {
+        const lidos = await store.readKeys(sessionId, type, faltando)
+        for (const id of faltando) {
+          const v = lidos?.[id]
+          if (v === undefined) { cache.set(chave(type, id), null); continue }
+          cache.set(chave(type, id), v)
+          resultado[id] = v
+        }
+      }
+      return resultado
+    },
+    async set(data) {
+      const writes = {}
+      for (const type of Object.keys(data)) {
+        writes[type] = {}
+        for (const id of Object.keys(data[type])) {
+          const valor = data[type][id]
+          cache.set(chave(type, id), valor === null || valor === undefined ? null : valor)
+          writes[type][id] = valor ?? null // null = apagar, é o que o Baileys espera poder pedir
+        }
+      }
+      await store.writeKeys(sessionId, writes)
+    }
+  }
+
+  const saveCreds = () => store.writeCreds(sessionId, creds)
+
+  return { state: { creds, keys }, saveCreds }
+}
+
+const { loadBaileys } = require("./baileys")
+module.exports = {
+  loadBaileys, useMorphoAuthState, MorphoAuthStore: require("./store").MorphoAuthStore, ...require("./codec") }

package/packages/core/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@morpho/core",
+  "version": "0.1.0",
+  "description": "Backend de sessão plugável para Baileys (WhatsApp). Camada 1 do projeto Morpho.",
+  "main": "index.js",
+  "license": "MIT"
+}

package/packages/core/store.js

@@ -0,0 +1,11 @@
+// Classe-base só para documentar a interface e falhar com uma mensagem clara em quem esquecer
+// de implementar algum método — não é obrigatório herdar dela (duck typing funciona normal).
+class MorphoAuthStore {
+  async readCreds(sessionId) { throw new Error("MorphoAuthStore.readCreds não implementado") }
+  async writeCreds(sessionId, creds) { throw new Error("MorphoAuthStore.writeCreds não implementado") }
+  async readKeys(sessionId, type, ids) { throw new Error("MorphoAuthStore.readKeys não implementado") }
+  async writeKeys(sessionId, writes) { throw new Error("MorphoAuthStore.writeKeys não implementado") }
+  async deleteSession(sessionId) { throw new Error("MorphoAuthStore.deleteSession não implementado") }
+  async listSessions() { throw new Error("MorphoAuthStore.listSessions não implementado") }
+}
+module.exports = { MorphoAuthStore }

package/packages/groups/README.md

@@ -0,0 +1,42 @@
+# morpho-socket/groups
+
+A **group metadata cache**, per socket. Without it every message sent to a group and every "is this person an admin?" check goes to WhatsApp — the bot gets slow and the number gets closer to rate limits.
+
+```js
+const { createGroups } = require("morpho-socket/groups")
+const groups = createGroups({ ttlMs: 120_000 })
+
+const sock = makeWASocket({ /* … */, cachedGroupMetadata: groups.cachedGroupMetadata })  // can be created before the socket exists
+groups.install(sock)                       // sock.groupMetadata(jid) now uses the cache
+await groups.loadAll()                     // optional, on connect: one query fills every group
+
+await groups.get(jid)                      // metadata (cached or one query); null if the jid is not a group
+await groups.isAdmin(jid, userJid, userLid)
+```
+
+`install(sock)` replaces `sock.groupMetadata` with the cached version (the original stays available as `sock.groupMetadataFresh`) and is idempotent. Create **one instance per socket**.
+
+## What it solves
+
+| Problem | Solution |
+|---|---|
+| The same lookup, over and over | TTL cache (`ttlMs`, default 120 s; `ttl` also accepts a function so it can change at runtime) with an LRU limit (`max`, 3000) |
+| 50 messages arrive in a new group at once | concurrent requests become **one** query |
+| WhatsApp refuses the query (rate limit) | serves stale data up to `maxStaleMs` (30 min); with no stale data the error propagates |
+| Bot was removed / group unreachable | after an error with no stale data the group "rests" for `errorTtlMs` (5 s): 50 messages = 1 query, not 50 |
+| The group changed | `groups.update`, `group-participants.update`, and any `groupParticipantsUpdate` / `groupSettingUpdate` / … made by the bot drop that group's cache. `groups.upsert` (bot joined) fills it |
+| A query that came back already outdated | if the group changed while it was in flight, the result is **not** cached |
+
+## API
+
+`createGroups(options)` → `{ install, get, admins, isAdmin, loadAll, cachedGroupMetadata, invalidate, set, clear, stats, cache }`
+
+- `admins(jid)` → `Set` of every id (phone, LID, device-less) of the group's admins
+- `isAdmin(jid, ...ids)` → understands `@lid`, phone JIDs, the `:12` device suffix and Baileys 7's `lid` / `phoneNumber` fields
+- `install(sock)` returns a handle with the same methods plus `uninstall()`
+- `stats()` → `{ hits, fetches, coalesced, stale, errors, size }`
+- Options: `ttlMs` · `ttl` · `max` · `maxStaleMs` · `errorTtlMs` · `cache` (a ready-made `createCache()`) · `intervene: false` (don't replace `sock.groupMetadata`; cache + events only)
+
+`createCache(options)` is the pure cache (`get(jid, load)`, `set`, `invalidate`, `clear`, `stats`) with no socket involved. Also exported: `install(sock, options)` (shortcut), `isGroupJid`, `stripDevice`, `MUTATING_METHODS`.
+
+If you use [`context`](../context), `g.isAdmin()` and the group actions read through `sock.groupMetadata`, so installing this cache speeds them up automatically.

package/packages/groups/index.js

@@ -0,0 +1,205 @@
+// @morpho/groups
+//
+// Cache dos dados de grupo (membros, admins, assunto) por socket. Sem ele, TODA mensagem enviada num grupo e TODA
+// checagem "é admin?" consulta o WhatsApp: o bot fica lento e o número fica mais exposto a limite de uso.
+//
+//   const { criarGrupos } = require("@morpho/groups")
+//   const grupos = criarGrupos({ ttlMs: 120_000 })
+//   const sock = makeWASocket({ ..., cachedGroupMetadata: grupos.cachedGroupMetadata }) // já pode passar antes do sock existir
+//   grupos.instalar(sock)                       // sock.groupMetadata(jid) passa a usar o cache
+//   await grupos.carregarTodos()                // opcional: ao conectar, 1 consulta enche o cache de todos os grupos
+//   await grupos.obter(jid)                     // metadados (do cache, ou 1 consulta)
+//   await grupos.ehAdmin(jid, userJid, userLid) // true/false (entende @lid e @s.whatsapp.net)
+//
+// Regras:
+//  - vale ttlMs (120 s) e é descartado na hora quando o grupo muda (evento) ou quando o próprio bot muda o grupo;
+//  - N pedidos iguais ao mesmo tempo viram UMA consulta;
+//  - se o WhatsApp recusar a consulta, usa o dado antigo (até maxVelhoMs, 30 min); sem dado antigo, o erro passa;
+//  - depois de um erro sem dado antigo, o grupo "descansa" ttlErroMs (5 s) antes de ser consultado de novo
+//    (bot expulso do grupo + 50 mensagens = 1 consulta, não 50);
+//  - uma consulta que ficou velha no caminho (o grupo mudou enquanto ela voltava) nunca entra no cache.
+
+const MARK = Symbol.for("morpho.groups")
+const isGroupJid = jid => typeof jid === "string" && jid.endsWith("@g.us")
+
+// métodos do socket que mudam o grupo: ao terminar (dando certo ou não), o cache daquele grupo é descartado
+const MUTATING_METHODS = ["groupParticipantsUpdate", "groupSettingUpdate", "groupUpdateSubject", "groupUpdateDescription",
+  "groupToggleEphemeral", "groupMemberAddMode", "groupJoinApprovalMode", "groupRevokeInvite", "groupRequestParticipantsUpdate"]
+
+// "5511@s.whatsapp.net", "5511:12@s.whatsapp.net" e "5511:12@s.whatsapp.net " viram "5511@s.whatsapp.net"
+const stripDevice = j => (j ? String(j).trim().replace(/:\d+(?=@)/, "") : "")
+
+// ---------------------------------------------------------------------------------------------
+// O cache em si (não conhece socket nem WhatsApp: recebe a função que busca)
+// ---------------------------------------------------------------------------------------------
+function createCache({ ttl, ttlMs = 120_000, max = 3000, maxStaleMs = 30 * 60_000, errorTtlMs = 5000 } = {}) {
+  const entries = new Map()  // jid -> { dados, em }   (a ordem do Map é a do uso: o mais antigo sai primeiro)
+  const pending = new Map()    // jid -> Promise (consulta em andamento)
+  const generation = new Map()   // jid -> número que sobe a cada invalidação
+  const failures = new Map()    // jid -> { erro, em }
+  const stats = { hits: 0, fetches: 0, coalesced: 0, stale: 0, errors: 0 }
+
+  // `ttl` (nome antigo do Morvyn) pode ser número ou função (lida a cada consulta, para o painel mudar sem reiniciar)
+  const ttlNow = () => { const v = ttl ?? ttlMs; return typeof v === "function" ? v() : v }
+  const fresh = e => e && Date.now() - e.em < ttlNow()
+  const gen = jid => generation.get(jid) || 0
+
+  function save(jid, data) {
+    entries.delete(jid)
+    entries.set(jid, { data, em: Date.now() })
+    while (entries.size > max) entries.delete(entries.keys().next().value)
+  }
+
+  async function get(jid, load) {
+    const e = entries.get(jid)
+    if (fresh(e)) { stats.hits++; entries.delete(jid); entries.set(jid, e); return e.data }
+    if (pending.has(jid)) { stats.coalesced++; return pending.get(jid) }
+
+    const usableStale = e && Date.now() - e.em < maxStaleMs
+    if (e && !usableStale) entries.delete(jid)
+
+    const f = failures.get(jid)
+    if (f && Date.now() - f.em < errorTtlMs) {
+      if (usableStale) { stats.stale++; return e.data }
+      throw f.error
+    }
+
+    const g0 = gen(jid)
+    stats.fetches++
+    const p = (async () => {
+      try {
+        const data = await load()
+        failures.delete(jid)
+        if (gen(jid) === g0) save(jid, data)
+        return data
+      } catch (error) {
+        stats.errors++
+        if (usableStale) { stats.stale++; return e.data } // o WhatsApp recusou: melhor um dado antigo do que nenhum
+        if (gen(jid) === g0) failures.set(jid, { error, em: Date.now() })
+        throw error
+      } finally {
+        if (pending.get(jid) === p) pending.delete(jid)
+      }
+    })()
+    pending.set(jid, p)
+    return p
+  }
+
+  // dado que já veio de outra consulta (ex.: groupFetchAllParticipating): entra sem gastar consulta
+  function set(jid, data) { failures.delete(jid); save(jid, data) }
+
+  function invalidate(jid) {
+    generation.set(jid, gen(jid) + 1)
+    entries.delete(jid); pending.delete(jid); failures.delete(jid)
+  }
+
+  function clear() {
+    for (const j of new Set([...entries.keys(), ...pending.keys(), ...failures.keys()])) generation.set(j, gen(j) + 1)
+    entries.clear(); pending.clear(); failures.clear()
+  }
+
+  return { get, set, invalidate, clear, size: () => entries.size, stats: () => ({ ...stats, size: entries.size }) }
+}
+
+// ---------------------------------------------------------------------------------------------
+// Ligação com o socket do Baileys
+// ---------------------------------------------------------------------------------------------
+// criarGrupos() pode ser criado ANTES do socket (para passar o cachedGroupMetadata ao makeWASocket) e ligado depois.
+function createGroups(options = {}) {
+  const cache = options.cache || createCache(options)
+  const intervene = options.intervene !== false // false: não troca sock.groupMetadata (só cache + eventos)
+  let sock = null
+  let fetchingAll = null // dedupe de groupFetchAllParticipating
+  let undo = []
+
+  const fetchOne = jid => {
+    if (!sock) throw new Error("@morpho/groups: chame instalar(sock) antes de consultar grupos.")
+    return (sock.groupMetadataFresh || sock.groupMetadata).call(sock, jid)
+  }
+
+  async function get(jid) {
+    if (!isGroupJid(jid)) return null
+    return cache.get(jid, () => fetchOne(jid))
+  }
+
+  // o que o Baileys consulta ao ENVIAR em grupo. Nunca lança (se falhar, o Baileys pergunta ao WhatsApp sozinho).
+  async function cachedGroupMetadata(jid) {
+    if (!sock || !isGroupJid(jid)) return undefined
+    try { return (await get(jid)) ?? undefined } catch { return undefined }
+  }
+
+  // Todos os grupos de uma vez (1 consulta). Enche o cache e devolve { jid: metadados }.
+  // Chamadas ao mesmo tempo viram uma só.
+  function loadAll() {
+    if (!sock) return Promise.reject(new Error("@morpho/groups: chame instalar(sock) antes de carregarTodos()."))
+    if (fetchingAll) return fetchingAll
+    const p = (async () => {
+      const all = await sock.groupFetchAllParticipating()
+      for (const [jid, meta] of Object.entries(all || {})) if (isGroupJid(jid)) cache.set(jid, meta)
+      return all || {}
+    })().finally(() => { if (fetchingAll === p) fetchingAll = null })
+    fetchingAll = p
+    return p
+  }
+
+  // Quem é admin do grupo. Aceita qualquer forma de identificar a pessoa (telefone e/ou @lid): o Baileys 7 entrega
+  // participants com id, lid e phoneNumber, e o que vale depende do grupo.
+  async function admins(jid) {
+    const meta = await get(jid)
+    const set = new Set()
+    for (const p of meta?.participants || [])
+      if (p.admin === "admin" || p.admin === "superadmin")
+        for (const j of [p.id, p.lid, p.phoneNumber, p.jid]) if (j) set.add(stripDevice(j))
+    return set
+  }
+
+  async function isAdmin(jid, ...ids) {
+    const set = await admins(jid)
+    return ids.flat().filter(Boolean).some(j => set.has(stripDevice(j)))
+  }
+
+  function install(s) {
+    if (s[MARK]) return s[MARK]
+    sock = s
+    const pristine = s.groupMetadata // para desinstalar() devolver exatamente a função que estava lá
+    const original = typeof pristine === "function" ? pristine.bind(s) : null
+
+    if (intervene && original) {
+      s.groupMetadataFresh = original
+      s.groupMetadata = jid => get(jid)
+    }
+    for (const name of MUTATING_METHODS) {
+      if (typeof s[name] !== "function") continue
+      const before = s[name]
+      const bound = before.bind(s)
+      s[name] = async (jid, ...rest) => { try { return await bound(jid, ...rest) } finally { cache.invalidate(jid) } }
+      undo.push(() => { s[name] = before })
+    }
+    if (intervene && original) undo.push(() => { s.groupMetadata = pristine; delete s.groupMetadataFresh })
+
+    const listen = (name, fn) => s.ev?.on?.(name, fn)
+    listen("groups.update", ups => { for (const u of ups || []) if (u?.id) cache.invalidate(u.id) })
+    listen("groups.upsert", metas => { for (const m of metas || []) if (m?.id) cache.set(m.id, m) })
+    listen("group-participants.update", ev => { if (ev?.id) cache.invalidate(ev.id) })
+
+    const handle = {
+      get, admins, isAdmin, loadAll, cachedGroupMetadata,
+      invalidate: jid => cache.invalidate(jid), set: (jid, meta) => cache.set(jid, meta),
+      clear: () => cache.clear(), stats: () => cache.stats(), cache,
+      uninstall() { for (const f of undo.reverse()) f(); undo = []; delete s[MARK]; sock = null }
+    }
+    s[MARK] = handle
+    return handle
+  }
+
+  return {
+    install, get, admins, isAdmin, loadAll, cachedGroupMetadata, cache,
+    invalidate: jid => cache.invalidate(jid), set: (jid, meta) => cache.set(jid, meta),
+    clear: () => cache.clear(), stats: () => cache.stats()
+  }
+}
+
+// atalho: instalar(sock, { cache?, ttlMs?, ... }) -> handle (idempotente)
+const install = (sock, options = {}) => sock[MARK] || createGroups(options).install(sock)
+
+module.exports = { createGroups, createCache, install, isGroupJid, stripDevice, MUTATING_METHODS }

package/packages/groups/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@morpho/groups",
+  "version": "0.1.0",
+  "description": "Cache de metadados de grupo do WhatsApp por socket: TTL, consultas simultâneas viram uma, dado antigo quando o WhatsApp recusa, invalidação por evento e cachedGroupMetadata pronto para o Baileys.",
+  "main": "index.js",
+  "license": "MIT"
+}

package/packages/interactive/README.md

@@ -0,0 +1,41 @@
+# morpho-socket/interactive
+
+**Native interactive messages** — image + text + buttons, and the selection list that opens to pick from (like WhatsApp Business menus) — and reading the tap.
+
+Baileys has no ready-made `sendMessage` for this: the message is built by hand and relayed with the `biz` nodes WhatsApp needs to draw the buttons. Morpho does that for you.
+
+```js
+const { createInteractive } = require("morpho-socket/interactive")
+const ui = createInteractive({ mark: "mybot:" })    // every id this bot sends starts with the mark
+
+await ui.send(sock, jid, {
+  body: "Pick one", footer: "…",
+  image: buffer, imageId: "menu",                   // imageId: the image upload is reused for 6 h
+  buttons: [
+    ui.button.reply("Menu", "menu"),                // quick reply: the bot receives the id as if typed
+    ui.button.link("Website", "https://example.com"),
+    ui.button.list("Categories", [
+      ui.section("Games", [ui.row("Tic-tac-toe", "play against me", "ttt")]),
+    ]),
+  ],
+  msg,                                              // optional: quote the message that asked for the menu
+  mentions,                                         // optional: JIDs mentioned as @number in the body
+})
+
+ui.parseSelection(msg, { sock })                    // "menu" | "ttt" | … | null
+```
+
+`parseSelection` returns the id **without the mark**, and `null` when the tap isn't ours: it checks the mark, and ignores taps on another bot's menu in the same group (the replied-to message must be from this bot).
+
+## API
+
+`createInteractive({ mark = "mp:" })` → `{ mark, button, section, row, send, parseSelection, quoteOf, extraNodes }`
+
+- `button.reply(text, id)` · `button.link(text, url)` · `button.list(title, sections)`
+- `section(title, rows)` · `row(title, description, id)`
+- `send(sock, jid, { body, footer, image, imageId, buttons, msg, mentions })` → the sent message
+
+## Good to know
+
+- This relies on WhatsApp behavior that is **not publicly documented**; it can stop working if WhatsApp changes the format. Always provide a text fallback — [`context`](../context)'s `g.reply({ body, buttons, fallback })` does: if the interactive send fails, the command is still answered in plain text.
+- With `context`, a tap on one of your buttons becomes `g.text` (for example `"menu games"`), so it flows through your commands like typed text.