morpho-socket 0.0.0-stage → 0.3.0

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(4001) },                  // `${a}${g.readMore}${b}` -> WhatsApp folds b behind "Read more"
+
+    // 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" }

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.