morpho-socket 0.4.1 → 0.5.0

package/README.md

@@ -14,7 +14,7 @@ npm install morpho-socket @whiskeysockets/baileys
 
 ## Requirements
 
-- **Node.js ≥ 22.5** (`store-sqlite` and `kv` use the built-in `node:sqlite`)
+- **Node.js ≥ 22.12** (Baileys 7 is ESM and Morpho loads it with `require`, which needs 22.12+; `store-sqlite` and `kv` use the built-in `node:sqlite`)
 - **Baileys** installed in your own project (Morpho loads it from there; it is not bundled)
 - **ffmpeg** on the `PATH`, only if you send voice notes from non-Opus audio
 
@@ -41,6 +41,8 @@ Morpho is CommonJS.
 | Relations between two people (couple, friend, parent, team…) with limits | [`links`](packages/links) |
 | Do something later or on repeat (reminders, daily open/close), surviving restarts | [`scheduler`](packages/scheduler) |
 | Conversations of several messages: confirmations, forms, games, reply-to-answer | [`ask`](packages/ask) |
+| Baileys changes a field or a payload and every layer above breaks | [`events`](packages/events) — Morpho's own events (`message`, `member.*`) with a stable shape |
+| "What is WhatsApp actually sending me?" (LID without number, new fields) | [`capture`](packages/capture) — masked capture, alerts and fixtures |
 
 ## A quick look
 

package/docs/building-a-bot.md

@@ -399,4 +399,4 @@ my-bot/
 - **Spread out startup.** `pool.startAll(items, { intervalMs })` opens connections one after another rather than all at once.
 - **Always give interactive messages a `fallback`.**
 - **ffmpeg** must be on the `PATH` to send voice notes from non-Opus audio.
-- **Node ≥ 22.5** is required by `store-sqlite` and `kv`. They print an `ExperimentalWarning` from Node itself; it is harmless.
+- **Node ≥ 22.12** is required: Baileys 7 is ESM and Morpho loads it with `require`. `store-sqlite` and `kv` also need `node:sqlite` (22.5+). They print an `ExperimentalWarning` from Node itself; it is harmless.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "morpho-socket",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Blocos para bots de WhatsApp sobre o Baileys",
   "license": "MIT",
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=22.12.0"
   },
   "peerDependencies": {
     "@whiskeysockets/baileys": "*"
@@ -34,7 +34,8 @@
     "./links": "./packages/links/index.js",
     "./scheduler": "./packages/scheduler/index.js",
     "./ask": "./packages/ask/index.js",
-    "./capture": "./packages/capture/index.js"
+    "./capture": "./packages/capture/index.js",
+    "./events": "./packages/events/index.js"
   },
   "scripts": {
     "test": "node test/run-all.js"

package/packages/capture/index.js

@@ -21,7 +21,7 @@ const path = require("node:path")
 const crypto = require("node:crypto")
 
 const EVENTS = [
-  "messages.upsert", "messages.update", "lid-mapping.update", "group-participants.update", "groups.upsert",
+  "messages.upsert", "messages.update", "messages.reaction", "messages.delete", "group.join-request", "lid-mapping.update", "group-participants.update", "groups.upsert",
   "groups.update", "contacts.upsert", "contacts.update", "connection.update", "call"
 ]
 const FRAME_TAGS = ["message", "notification", "call"]

package/packages/events/README.md

@@ -0,0 +1,53 @@
+# morpho-socket/events
+
+Morpho's **own events**, with a shape that does not change when Baileys or WhatsApp do. The Baileys adapter (7.0.0-rc14) lives in one file; everything above listens to Morpho's events, not to Baileys'.
+
+```js
+const { createEvents } = require("morpho-socket/events")
+const events = createEvents({ identity })     // identity = createIdentity() from morpho-socket/jid (recommended)
+events.attachPool(pool)                       // or events.attach(sock, sessionId)
+
+events.on("message", m => {
+  m.chatKind      // "group" | "private" | "status" | "broadcast" | "newsletter"
+  m.source        // "notify" (new) | "append" (history, or sent from the phone)
+  m.fromMe, m.id, m.chatId, m.addressingMode
+  m.sender        // { jid, lid, pn, number, formatted, resolved, isBot, source }  <- already resolved
+  m.content       // parse() from morpho-socket/message
+  m.raw, m.sock, m.session
+})
+
+events.on("member.join", e => { e.chatId; e.member; e.by })
+events.on("member.leave", e => { e.kicked })  // true: someone else removed them; false: they left
+// also member.promote, member.demote, member.update (anything else Baileys reports)
+
+events.on("reaction", e => { e.emoji; e.removed; e.messageId; e.by })        // e.by = who reacted
+events.on("message.edit", e => { e.messageId; e.content; e.by })             // content parsed like a normal message
+events.on("message.delete", e => { e.messageId; e.by })                      // by = null when it comes from history
+events.on("chat.clear", e => { e.chatId })
+events.on("receipt", e => { e.status; e.user })                              // "delivered" | "read" | "played"
+events.on("call", e => { e.status; e.from; e.isVideo; e.groupId })
+events.on("connection", e => { e.state; e.error; e.online; e.hasQr })        // partial updates; the QR itself is never delivered
+events.on("group.update", e => { e.changes; e.by })                          // { subject, description, onlyAdminsSend, onlyAdminsEdit, membersCanAdd, joinApproval, ephemeralDuration }
+events.on("group.new", e => { e.subject; e.size })                           // the bot entered or created a group
+events.on("group.join-request", e => { e.action; e.method; e.member; e.by })
+```
+
+`member` and `by` are `{ jid, lid, pn, number, formatted, resolved, source, admin }`, whether Baileys sent participants as strings (6) or as objects with `lid` / `phoneNumber` (7).
+
+## Behavior
+
+- Events keep the order Baileys delivered them (an `add` and a later `remove` of the same person never swap), but listeners run without holding the next event: a slow command does not delay the next message.
+- A listener that throws never stops the other listeners or the bot: the error goes to `onError` and is counted in `events.stats.listenerErrors`. The adapter itself never throws into Baileys (`stats.adapterErrors`).
+- `events.stats.emitted` counts what was emitted per event name.
+- Nothing here touches the network. Number resolution uses what `jid` already knows (`participantAlt`, `phoneNumber`, the LID map).
+
+## Why
+
+The first time WhatsApp moved people to `@lid`, the sender moved from one field to another and each package had to learn that by itself. Here the difference is absorbed once. Use `morpho-socket/capture` to see what Baileys really delivers and to build fixtures for this adapter.
+
+- **No listener, no work.** An adapter that nobody listens to does nothing (receipts and `messages.update` are frequent and cost an identity lookup each).
+- In `messages.update`, only revoke (delete) and edit become events. Acks, poll votes and event responses are counted in `stats.ignored` and left to the packages that already handle them (`sent`).
+
+## Not covered yet
+
+Presence, chats/contacts sync, blocklist, labels, newsletters, history sync and `creds.update` still come from Baileys directly (the pool already owns `creds.update`). They enter the same way: one adapter function and one test.

package/packages/events/index.js

@@ -0,0 +1,280 @@
+// @morpho/events
+//
+// Morpho's OWN events, with a shape that does not depend on the Baileys version. The Baileys adapter lives in this one
+// file: when WhatsApp or Baileys change something (the move to @lid, a field that moved, a payload that went from
+// strings to objects), the fix goes here and nothing above notices.
+//
+//   const { createEvents } = require("morpho-socket/events")
+//   const events = createEvents({ identity })            // identity: morpho-socket/jid (optional, but without it numbers are not resolved)
+//   events.attachPool(pool)                              // or events.attach(sock, sessionId)
+//
+//   events.on("message", m => {
+//     m.id  m.chatId  m.chatKind        // "group" | "private" | "status" | "broadcast" | "newsletter"
+//     m.fromMe  m.source                // source: "notify" (new) | "append" (history / sent from the phone)
+//     m.sender                          // { jid, lid, pn, number, formatted, resolved, isBot, source }
+//     m.addressingMode                  // "lid" | "pn" | null
+//     m.content                         // morpho-socket/message parse(): type, text, mentions, media, quoted...
+//     m.raw  m.sock  m.session          // the Baileys message, the socket and the session id, when you need them
+//   })
+//   events.on("member.join" | "member.leave" | "member.promote" | "member.demote" | "member.update", e => {
+//     e.chatId  e.member  e.by  e.action  // member/by: { jid, lid, pn, number, formatted, resolved, source, admin }
+//     e.kicked                            // member.leave only: true when someone else removed them
+//   })
+//
+//   events.on("reaction", e => e.emoji, e.removed, e.messageId, e.by)
+//   events.on("message.edit", e => e.messageId, e.content (parsed new content), e.by)
+//   events.on("message.delete", e => e.messageId, e.by)            // `by` is null when it comes from history
+//   events.on("receipt", e => e.status)                            // "delivered" | "read" | "played", e.user
+//   events.on("call", e => e.status, e.from, e.isVideo, e.groupId)
+//   events.on("connection", e => e.state, e.error, e.online)       // partial updates: only what changed is filled
+//   events.on("group.update" | "group.new" | "group.join-request", ...)
+//
+// Rules: a listener that throws never stops the others or the bot (it is counted in stats and sent to onError);
+// the adapter never throws into Baileys; nothing here talks to the network.
+
+const { kind, normalize, digits, formatNumber } = require("../jid")
+
+const lazyParse = () => require("../message").parse
+const lazyToNumber = () => require("../message").toNumber
+const REVOKE = 1 // WAMessageStubType.REVOKE in Baileys 7
+
+function chatKindOf(chatId) {
+  if (chatId === "status@broadcast") return "status"
+  const k = kind(chatId)
+  if (k === "group") return "group"
+  if (k === "broadcast") return "broadcast"
+  if (k === "newsletter") return "newsletter"
+  return "private"
+}
+
+function createEvents({ identity, parse = lazyParse(), toNumber = lazyToNumber(), onError = (e, where) => console.error(`[events] ${where}:`, e) } = {}) {
+  const listeners = new Map()
+  const stats = { emitted: {}, ignored: {}, listenerErrors: 0, adapterErrors: 0 }
+  const bump = (o, k) => { o[k] = (o[k] || 0) + 1 }
+
+  function on(name, fn) {
+    if (typeof fn !== "function") throw new TypeError("events.on: pass a function")
+    if (!listeners.has(name)) listeners.set(name, new Set())
+    listeners.get(name).add(fn)
+    return () => listeners.get(name)?.delete(fn)
+  }
+
+  async function emit(name, payload) {
+    bump(stats.emitted, name)
+    for (const fn of [...(listeners.get(name) || [])]) {
+      try { await fn(payload) } catch (e) { stats.listenerErrors++; try { onError(e, name) } catch { /* even the error handler must not break the bot */ } }
+    }
+  }
+
+  // ---- identity helpers ----
+  function basicSender(raw, sock) {
+    const k = raw?.key || {}
+    const jid = k.fromMe ? sock?.user?.id : (kind(k.remoteJid) === "group" ? k.participant : k.remoteJid)
+    const lid = kind(jid) === "lid" ? normalize(jid) : null
+    const alt = kind(jid) === "group" ? null : (kind(k.remoteJid) === "group" ? k.participantAlt : k.remoteJidAlt)
+    const number = digits(jid || "") || digits(alt || "")
+    return { jid: jid || null, lid, pn: number ? `${number}@s.whatsapp.net` : null, number, formatted: formatNumber(number), resolved: !!number, isBot: !!k.fromMe, source: number ? "message" : null, group: null }
+  }
+
+  async function senderOf(raw, sock, session) {
+    if (!identity) return basicSender(raw, sock)
+    return identity.resolveSender(raw, sock, session) // never throws (falls back to what came in the message)
+  }
+
+  // a participant/author as Baileys 6 (string) or 7 (object {id, lid, phoneNumber, admin}) delivers it
+  async function person(p, { sock, session, group, pn: pnHint } = {}) {
+    const o = typeof p === "string" ? { id: p } : (p || {})
+    const id = o.id || o.jid || null
+    const lid = o.lid ? normalize(o.lid) : (kind(id) === "lid" ? normalize(id) : null)
+    let pn = [o.phoneNumber, o.pn, pnHint, kind(id) === "pn" ? id : null].find(x => kind(x) === "pn") || null
+    let number = digits(pn || ""), source = number ? (kind(id) === "pn" ? "message" : "alt") : null
+    if (!number && lid && identity) {
+      const r = await identity.resolveJid(lid, { sock, clientId: session, group }).catch(() => null)
+      if (r?.number) { number = r.number; source = r.source }
+    }
+    if (number && !pn) pn = `${number}@s.whatsapp.net`
+    const admin = o.admin ?? (o.isSuperAdmin ? "superadmin" : o.isAdmin ? "admin" : null)
+    return { jid: normalize(id), lid, pn: pn ? normalize(pn) : null, number, formatted: formatNumber(number), resolved: !!number, source, admin }
+  }
+  const samePerson = (a, b) => {
+    const ids = x => [x?.jid, x?.lid, x?.pn].filter(Boolean).map(normalize)
+    const bs = new Set(ids(b))
+    return ids(a).some(x => bs.has(x))
+  }
+
+  // ---- adapters (Baileys 7.0.0-rc14) ----
+  async function onUpsert(sock, session, data) {
+    const messages = Array.isArray(data?.messages) ? data.messages : []
+    for (const raw of messages) {
+      try {
+        const k = raw?.key || {}
+        const content = parse(raw)
+        const m = {
+          session, sock, raw,
+          id: k.id || null,
+          chatId: k.remoteJid || null,
+          chatKind: chatKindOf(k.remoteJid),
+          fromMe: !!k.fromMe,
+          source: data?.type === "append" ? "append" : (data?.type || "notify"),
+          addressingMode: k.addressingMode || null,
+          ts: content?.timestamp || null,
+          sender: await senderOf(raw, sock, session),
+          content
+        }
+        emit("message", m) // not awaited: a slow listener (a command that downloads something) must not hold the next message
+      } catch (e) { stats.adapterErrors++; try { onError(e, "adapter:messages.upsert") } catch { /* swallowed */ } }
+    }
+  }
+
+  const MEMBER_EVENT = { add: "member.join", remove: "member.leave", promote: "member.promote", demote: "member.demote" }
+  async function onParticipants(sock, session, u) {
+    try {
+      if (!u || !Array.isArray(u.participants)) return
+      const group = u.id
+      const by = u.author ? await person({ id: u.author }, { sock, session, group, pn: u.authorPn }) : null
+      for (const p of u.participants) {
+        const member = await person(p, { sock, session, group })
+        const name = MEMBER_EVENT[u.action] || "member.update"
+        const e = { session, sock, chatId: group, action: u.action, member, by, raw: u }
+        if (name === "member.leave") e.kicked = !!by && !samePerson(by, member)
+        emit(name, e)
+      }
+    } catch (e) { stats.adapterErrors++; try { onError(e, "adapter:group-participants.update") } catch { /* swallowed */ } }
+  }
+
+
+  const wanted = (...names) => names.some(n => listeners.get(n)?.size)
+  const safe = async (where, fn) => {
+    try { await fn() } catch (e) { stats.adapterErrors++; try { onError(e, `adapter:${where}`) } catch { /* swallowed */ } }
+  }
+  const base = (sock, session) => ({ session, sock })
+  const whoKey = (key, sock, session) => senderOf({ key }, sock, session)
+  const seconds = v => { const n = toNumber(v); return n ? (n > 1e11 ? Math.floor(n / 1000) : n) : null }
+
+  async function onReaction(sock, session, list) {
+    if (!wanted("reaction")) return
+    await safe("messages.reaction", async () => {
+      for (const { key, reaction } of Array.isArray(list) ? list : []) {
+        const by = reaction?.key ? await whoKey(reaction.key, sock, session) : null
+        emit("reaction", {
+          ...base(sock, session), chatId: key?.remoteJid || null, chatKind: chatKindOf(key?.remoteJid), messageId: key?.id || null,
+          targetFromMe: !!key?.fromMe, by, emoji: reaction?.text || "", removed: !reaction?.text, ts: seconds(reaction?.senderTimestampMs), raw: { key, reaction }
+        })
+      }
+    })
+  }
+
+  // messages.update carries many things (acks, poll votes...). Only revoke and edit mean something to a bot for now.
+  async function onMessagesUpdate(sock, session, list) {
+    if (!wanted("message.delete", "message.edit")) return
+    await safe("messages.update", async () => {
+      for (const u of Array.isArray(list) ? list : []) {
+        const key = u?.key || {}, up = u?.update || {}
+        if (up.messageStubType === REVOKE) {
+          emit("message.delete", { ...base(sock, session), chatId: key.remoteJid || null, chatKind: chatKindOf(key.remoteJid), messageId: key.id || null, by: await whoKey(key, sock, session), raw: u })
+        } else if (up.message?.editedMessage) {
+          const content = parse({ key, message: up.message, messageTimestamp: up.messageTimestamp })
+          emit("message.edit", { ...base(sock, session), chatId: key.remoteJid || null, chatKind: chatKindOf(key.remoteJid), messageId: key.id || null, by: await whoKey(key, sock, session), content, ts: seconds(up.messageTimestamp), raw: u })
+        } else bump(stats.ignored, "messages.update")
+      }
+    })
+  }
+
+  async function onMessagesDelete(sock, session, d) {
+    if (!wanted("message.delete", "chat.clear")) return
+    await safe("messages.delete", async () => {
+      if (d?.all && d.jid) return emit("chat.clear", { ...base(sock, session), chatId: d.jid, chatKind: chatKindOf(d.jid), raw: d })
+      for (const key of Array.isArray(d?.keys) ? d.keys : [])
+        emit("message.delete", { ...base(sock, session), chatId: key.remoteJid || null, chatKind: chatKindOf(key.remoteJid), messageId: key.id || null, by: null, raw: d })
+    })
+  }
+
+  async function onReceipt(sock, session, list) {
+    if (!wanted("receipt")) return
+    await safe("message-receipt.update", async () => {
+      for (const { key, receipt } of Array.isArray(list) ? list : []) {
+        const status = receipt?.playedTimestamp ? "played" : receipt?.readTimestamp ? "read" : "delivered"
+        emit("receipt", { ...base(sock, session), chatId: key?.remoteJid || null, chatKind: chatKindOf(key?.remoteJid), messageId: key?.id || null, status, user: receipt?.userJid ? await person({ id: receipt.userJid }, { sock, session, group: kind(key?.remoteJid) === "group" ? key.remoteJid : undefined }) : null, raw: { key, receipt } })
+      }
+    })
+  }
+
+  async function onCall(sock, session, list) {
+    if (!wanted("call")) return
+    await safe("call", async () => {
+      for (const c of Array.isArray(list) ? list : []) {
+        emit("call", { ...base(sock, session), id: c.id || null, status: c.status || null, chatId: c.chatId || null, from: c.from ? await person({ id: c.from }, { sock, session, pn: c.callerPn }) : null,
+          isVideo: !!c.isVideo, isGroup: !!c.isGroup, groupId: c.groupJid || null, date: c.date || null, offline: !!c.offline, raw: c })
+      }
+    })
+  }
+
+  async function onConnection(sock, session, u) {
+    if (!wanted("connection")) return
+    await safe("connection.update", async () => {
+      const err = u?.lastDisconnect?.error
+      emit("connection", { ...base(sock, session), state: u?.connection || null, isNewLogin: u?.isNewLogin ?? null, hasQr: !!u?.qr, online: u?.isOnline ?? null, receivedPendingNotifications: u?.receivedPendingNotifications ?? null,
+        error: err ? { code: err.output?.statusCode ?? err.statusCode ?? null, message: err.message ?? null } : null })
+    })
+  }
+
+  const GROUP_FIELDS = { subject: "subject", desc: "description", announce: "onlyAdminsSend", restrict: "onlyAdminsEdit", memberAddMode: "membersCanAdd", joinApprovalMode: "joinApproval", ephemeralDuration: "ephemeralDuration" }
+  async function onGroupsUpdate(sock, session, list) {
+    if (!wanted("group.update")) return
+    await safe("groups.update", async () => {
+      for (const u of Array.isArray(list) ? list : []) {
+        const changes = {}
+        for (const [from, to] of Object.entries(GROUP_FIELDS)) if (u?.[from] !== undefined) changes[to] = u[from]
+        const by = u?.author ? await person({ id: u.author }, { sock, session, group: u.id, pn: u.authorPn }) : null
+        emit("group.update", { ...base(sock, session), chatId: u?.id || null, changes, by, raw: u })
+      }
+    })
+  }
+  async function onGroupsUpsert(sock, session, list) {
+    if (!wanted("group.new")) return
+    await safe("groups.upsert", async () => {
+      for (const g of Array.isArray(list) ? list : [])
+        emit("group.new", { ...base(sock, session), chatId: g?.id || null, subject: g?.subject ?? null, size: g?.size ?? g?.participants?.length ?? null, addressingMode: g?.addressingMode || null, raw: g })
+    })
+  }
+  async function onJoinRequest(sock, session, r) {
+    if (!wanted("group.join-request")) return
+    await safe("group.join-request", async () => {
+      if (!r) return
+      emit("group.join-request", { ...base(sock, session), chatId: r.id || null, action: r.action || null, method: r.method || null,
+        member: await person({ id: r.participant }, { sock, session, group: r.id, pn: r.participantPn }),
+        by: r.author ? await person({ id: r.author }, { sock, session, group: r.id, pn: r.authorPn }) : null, raw: r })
+    })
+  }
+
+  function attach(sock, session = "default", { listen } = {}) {
+    const undo = []
+    // Building a payload is async (it resolves who is who). The queue keeps events in the order Baileys delivered them
+    // (add → remove of the same person); listeners themselves run without holding the queue.
+    let queue = Promise.resolve()
+    const ordered = fn => d => { queue = queue.then(() => fn(d)).catch(() => { stats.adapterErrors++ }) }
+    const add = (ev, fn) => {
+      if (listen) return listen(ev, fn) // the pool's `listen` already ignores events from a replaced socket
+      sock.ev.on(ev, fn); undo.push(() => sock.ev.off?.(ev, fn))
+    }
+    add("messages.upsert", ordered(d => onUpsert(sock, session, d)))
+    add("group-participants.update", ordered(d => onParticipants(sock, session, d)))
+    add("messages.reaction", ordered(d => onReaction(sock, session, d)))
+    add("messages.update", ordered(d => onMessagesUpdate(sock, session, d)))
+    add("messages.delete", ordered(d => onMessagesDelete(sock, session, d)))
+    add("message-receipt.update", ordered(d => onReceipt(sock, session, d)))
+    add("call", ordered(d => onCall(sock, session, d)))
+    add("connection.update", ordered(d => onConnection(sock, session, d)))
+    add("groups.update", ordered(d => onGroupsUpdate(sock, session, d)))
+    add("groups.upsert", ordered(d => onGroupsUpsert(sock, session, d)))
+    add("group.join-request", ordered(d => onJoinRequest(sock, session, d)))
+    return () => { for (const f of undo) try { f() } catch { /* socket already gone */ } }
+  }
+  function attachPool(pool) {
+    pool.on("socket", (session, sock, { listen } = {}) => { attach(sock, session, { listen }) })
+  }
+
+  return { on, attach, attachPool, stats, chatKindOf }
+}
+
+module.exports = { createEvents, chatKindOf }

package/packages/events/package.json

@@ -0,0 +1 @@
+{ "name": "@morpho/events", "version": "0.1.0", "description": "Morpho's own events with a stable shape (message, member.*) on top of the Baileys adapter.", "main": "index.js", "license": "MIT" }