morpho-socket 0.0.0-stage → 0.3.0

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.

package/packages/interactive/index.js

@@ -0,0 +1,92 @@
+// @morpho/interactive
+//
+// "Native" interactive messages: image + text + buttons and the selection list (the "MENU CATEGORIES" that opens to pick
+// from, like WhatsApp Business). Baileys has no ready-made sendMessage for this, so the message is hand-built
+// (interactiveMessage + nativeFlowMessage) and sent with relayMessage plus the "biz" nodes WhatsApp needs to draw buttons.
+//
+//   const { createInteractive } = require("@morpho/interactive")
+//   const ui = createInteractive({ mark: "mv:" })      // every id this bot sends starts with the mark
+//   await ui.send(sock, jid, { body: "Pick one", buttons: [ui.button.reply("Menu", "menu"), ui.button.link("Site", url)], msg })
+//   ui.parseSelection(msg, { sock })                   // -> "menu" | null  (id without the mark; null if not ours)
+const { parse } = require("../message")
+
+const stripDevice = j => (j ? j.replace(/:\d+(?=@)/, "") : null)
+const userPart = j => String(j).split("@")[0].split(":")[0]
+const IMAGE_TTL_MS = 6 * 3600e3
+
+function createInteractive({ mark = "mp:" } = {}) {
+  const button = {
+    // opens the selection list. sections = [{ title, rows: [row(...)] }]
+    list: (title, sections) => ({ name: "single_select", buttonParamsJson: JSON.stringify({ title, sections }) }),
+    // quick reply: when tapped the bot "receives" the id (e.g. "/menuadm") as if typed
+    reply: (text, id) => ({ name: "quick_reply", buttonParamsJson: JSON.stringify({ display_text: text, id: mark + id }) }),
+    link: (text, url) => ({ name: "cta_url", buttonParamsJson: JSON.stringify({ display_text: text, url, merchant_url: url }) })
+  }
+  const section = (title, rows) => ({ title, highlight_label: "", rows })
+  const row = (title, description, id) => ({ header: "", title, description: description || "", id: mark + id })
+
+  // quotes the message of whoever asked (the "!menu" bubble above the menu)
+  function quoteOf(sock, msg) {
+    if (!msg?.key?.id || !msg.message) return null
+    const m = msg.message
+    let quotedMessage = null
+    if (m.conversation) quotedMessage = { conversation: m.conversation }
+    else if (m.extendedTextMessage) quotedMessage = { extendedTextMessage: { text: m.extendedTextMessage.text, contextInfo: { mentionedJid: m.extendedTextMessage.contextInfo?.mentionedJid || [] } } }
+    else if (m.interactiveResponseMessage) quotedMessage = { conversation: m.interactiveResponseMessage.body?.text || "" } // tap on a list/button
+    else return null
+    const participant = msg.key.fromMe ? stripDevice(sock.user?.lid || sock.user?.id) : (msg.key.participant || msg.key.remoteJid)
+    return { stanzaId: msg.key.id, participant, quotedMessage }
+  }
+
+  // extra nodes: without them the buttons don't show. In private chats WhatsApp also wants the "bot" node.
+  function extraNodes(jid) {
+    const nodes = [{ tag: "biz", attrs: {}, content: [{ tag: "interactive", attrs: { type: "native_flow", v: "1" }, content: [{ tag: "native_flow", attrs: { v: "9", name: "mixed" } }] }] }]
+    if (!String(jid).endsWith("@g.us")) nodes.push({ tag: "bot", attrs: { biz_bot: "1" } })
+    return nodes
+  }
+
+  // The menu image is the same every time: upload once per socket and keep it for 6h (it was one upload per /menu).
+  const uploaded = new WeakMap() // sock -> Map(imageId -> { media, at })
+  async function prepareImage(sock, image, imageId, prepareWAMessageMedia) {
+    const store = imageId ? (uploaded.get(sock) || uploaded.set(sock, new Map()).get(sock)) : null
+    const hit = store?.get(imageId)
+    if (hit && Date.now() - hit.at < IMAGE_TTL_MS) return hit.media
+    const media = await prepareWAMessageMedia({ image }, { upload: sock.waUploadToServer })
+    store?.set(imageId, { media, at: Date.now() })
+    return media
+  }
+
+  // image (Buffer) is optional; mentions = JIDs cited as @number in the body. `baileys` only exists for tests (injection).
+  async function send(sock, jid, { image, imageId, body, footer, buttons, msg, mentions }, baileys) {
+    const { generateWAMessageFromContent, prepareWAMessageMedia } = baileys || require("../core/baileys").loadBaileys()
+    let header = { title: "", subtitle: "", hasMediaAttachment: false }
+    if (image) header = { title: "", subtitle: "", hasMediaAttachment: true, ...(await prepareImage(sock, image, imageId, prepareWAMessageMedia)) }
+
+    const interactiveMessage = { header, body: { text: body }, footer: { text: footer || "" }, nativeFlowMessage: { buttons, messageParamsJson: "" } }
+    const quote = quoteOf(sock, msg)
+    if (quote || mentions?.length) interactiveMessage.contextInfo = { ...(quote || {}), ...(mentions?.length ? { mentionedJid: mentions } : {}) }
+
+    const waMsg = generateWAMessageFromContent(jid, {
+      viewOnceMessage: { message: { messageContextInfo: { deviceListMetadata: {}, deviceListMetadataVersion: 2 }, interactiveMessage } }
+    }, { userJid: sock.user?.id })
+
+    await sock.relayMessage(jid, waMsg.message, { messageId: waMsg.key.id, additionalNodes: extraNodes(jid) })
+    return waMsg
+  }
+
+  // A tap on a button / list row: returns the id WITHOUT the mark (e.g. "menu games"), or null.
+  // Only ids with this bot's mark count, and a reply quoting ANOTHER number's message (another bot in the group) is ignored.
+  function parseSelection(msg, { sock } = {}) {
+    const m = parse(msg)
+    const id = m.selection?.id
+    if (typeof id !== "string" || !id.startsWith(mark)) return null
+    const author = m.context?.participant
+    const me = [sock?.user?.id, sock?.user?.lid].filter(Boolean).map(userPart)
+    if (author && me.length && !me.includes(userPart(author))) return null
+    return id.slice(mark.length)
+  }
+
+  return { mark, button, section, row, send, quoteOf, extraNodes, parseSelection }
+}
+
+module.exports = { createInteractive }

package/packages/interactive/package.json

@@ -0,0 +1 @@
+{ "name": "@morpho/interactive", "version": "0.1.0", "description": "Native WhatsApp interactive messages (image + text + buttons, selection lists) and parsing of the taps. Baileys has no ready-made sendMessage for this: the message is built by hand and relayed with the 'biz' nodes WhatsApp requires.", "main": "index.js", "dependencies": { "@morpho/message": "file:../message" }, "license": "MIT" }

package/packages/jid/README.md

@@ -0,0 +1,51 @@
+# morpho-socket/jid
+
+**Identity.** Find out who really sent a message.
+
+WhatsApp now identifies the same person in two ways: the phone-number JID (`5511…@s.whatsapp.net`) and an opaque **LID** (`123…@lid`) that is *not* the phone number. Depending on the Baileys version, the chat type and the person, a message arrives with one or the other. This module always gives you the same thing — the clean number (digits only), or `null` when it truly cannot be found — and tells you where the answer came from.
+
+```js
+const { createIdentity } = require("morpho-socket/jid")
+const identity = createIdentity({ store })          // store is optional; with it the LID map survives restarts
+
+identity.install(sock, clientId)                    // on every (re)connection: learns mappings from socket events
+
+const who = await identity.resolveSender(msg, sock, clientId)
+who.number      // "5511968111161" | null
+who.formatted   // "+55 (11) 96811-1161"
+who.pn          // "5511968111161@s.whatsapp.net" | null
+who.lid         // "123…@lid" | null
+who.isBot       // true when the sender is the bot's own number
+who.source      // "bot" | "message" | "alt" | "map" | "baileys" | "group" | "groups" | null
+who.resolved    // true when a number was found
+```
+
+## How a LID is resolved
+
+From the cheapest source to the most expensive:
+
+1. the pair Baileys 7 already sends in the message key (`participantAlt` / `remoteJidAlt`);
+2. the **remembered map** (memory, plus your store when it implements `getLid`/`setLid`);
+3. Baileys' own `signalRepository.lidMapping`, when available;
+4. the group's participant list (each member carries both ids — the whole group is learned at once);
+5. **warm-up**: one query for *all* the bot's groups. The map that holds in a group holds in private chats too, so anyone sharing a group with the bot gets resolved. Throttled (`warmUpIntervalMs`, 2 min) so an unresolvable LID cannot trigger one query per message.
+
+Identity **never throws**. If resolving fails, `resolveSender` falls back to what arrived in the message — a message is never lost because of a lookup.
+
+## API
+
+`createIdentity({ store, warmUpIntervalMs })` — one service for a multi-client bot (one resolver per client, one shared store):
+
+| | |
+|---|---|
+| `install(sock, clientId)` | start learning from `lid-mapping.update`, contacts and group events |
+| `resolveSender(msg, sock, clientId)` | → the object above |
+| `resolveJid(jid, { sock, clientId, group })` | → `{ number, source } \| null` |
+| `learnGroups(clientId, groups)` | learn from groups you already fetched (no extra query) |
+| `warmUp(sock, clientId, opts)` · `forClient(clientId)` · `fallback(msg, sock)` | lower level |
+
+`createResolver({ store, warmUpIntervalMs })` is the single-number version (`sender`, `resolveLid`, `learn`, `learnFrom`, `learnGroup`, `warmUp`, `install`).
+
+Utilities: `parts(jid)` · `kind(jid)` (`"pn" \| "lid" \| "group" \| "broadcast" \| "newsletter" \| "other"`) · `normalize(jid)` (drops device/agent) · `digits(value)` · `formatNumber(digits)` (Brazilian numbers get the local format, others `+<digits>`).
+
+No dependency on Baileys: everything specific to it is read from the `sock` you pass, and each source is optional.