morpho-socket 0.2.0 → 0.4.0

package/README.md

@@ -37,6 +37,10 @@ Morpho is CommonJS.
 | One object with everything about the current message | [`context`](packages/context) |
 | Commands from folders, aliases, admin/owner guards, antiflood | [`commands`](packages/commands) |
 | Bot data (economy, settings, cooldowns) with real transactions | [`kv`](packages/kv) |
+| Invites, challenges, trades: a request that expires if nobody answers | [`pending`](packages/pending) |
+| 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) |
 
 ## A quick look
 
@@ -143,7 +147,7 @@ module.exports = {
 
 - **[Building a bot with Morpho](docs/building-a-bot.md)** — a tour of every feature and how to combine them.
 - Each module has its own README with the full API:
-  [`core`](packages/core) · [`store-sqlite`](packages/store-sqlite) · [`store-file`](packages/store-file) · [`pool`](packages/pool) · [`message`](packages/message) · [`jid`](packages/jid) · [`groups`](packages/groups) · [`media`](packages/media) · [`reply`](packages/reply) · [`interactive`](packages/interactive) · [`presence`](packages/presence) · [`sent`](packages/sent) · [`context`](packages/context) · [`commands`](packages/commands) · [`kv`](packages/kv)
+  [`core`](packages/core) · [`store-sqlite`](packages/store-sqlite) · [`store-file`](packages/store-file) · [`pool`](packages/pool) · [`message`](packages/message) · [`jid`](packages/jid) · [`groups`](packages/groups) · [`media`](packages/media) · [`reply`](packages/reply) · [`interactive`](packages/interactive) · [`presence`](packages/presence) · [`sent`](packages/sent) · [`context`](packages/context) · [`commands`](packages/commands) · [`kv`](packages/kv) · [`pending`](packages/pending) · [`links`](packages/links) · [`scheduler`](packages/scheduler) · [`ask`](packages/ask)
 
 ## Testing
 

package/docs/building-a-bot.md

@@ -97,7 +97,7 @@ const g = await contexts.build({ sock, msg, clientId })
 | who it's about | `await g.who()` — the mentioned person, else the replied-to author |
 | permissions | `g.isOwner` · `await g.isAdmin()` · `await g.isBotAdmin()` |
 | to answer | `g.reply(…)` · `g.send(jid, …)` · `g.react("👍")` · `g.edit(sent, …)` |
-| group info and actions | `g.group()` · `g.members()` · `g.kick()` · `g.promote()` · … |
+| group info and actions | `g.group()` · `g.members()` · `g.kick()` · `g.promote()` · `g.tagAll(text)` · … (`g.readMore` = the "Read more…" fold) |
 | media | `g.download()` · `g.media()` |
 
 Your bot's rules plug in through `createContext` options and `extend`:

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "morpho-socket",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Blocos para bots de WhatsApp sobre o Baileys",
   "license": "MIT",
-  "engines": { "node": ">=22.5.0" },
-  "peerDependencies": { "@whiskeysockets/baileys": "*" },
-  "files": ["packages", "README.md", "docs"],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "peerDependencies": {
+    "@whiskeysockets/baileys": "*"
+  },
+  "files": [
+    "packages",
+    "README.md",
+    "docs"
+  ],
   "exports": {
     "./core": "./packages/core/index.js",
     "./store-sqlite": "./packages/store-sqlite/index.js",
@@ -21,7 +29,14 @@
     "./sent": "./packages/sent/index.js",
     "./context": "./packages/context/index.js",
     "./commands": "./packages/commands/index.js",
-    "./kv": "./packages/kv/index.js"
+    "./kv": "./packages/kv/index.js",
+    "./pending": "./packages/pending/index.js",
+    "./links": "./packages/links/index.js",
+    "./scheduler": "./packages/scheduler/index.js",
+    "./ask": "./packages/ask/index.js",
+    "./capture": "./packages/capture/index.js"
   },
-  "scripts": { "test": "node test/run-all.js" }
+  "scripts": {
+    "test": "node test/run-all.js"
+  }
 }

package/packages/ask/README.md

@@ -0,0 +1,99 @@
+# morpho-socket/ask
+
+Conversations that take **more than one message**. A command answers one message; sometimes you need to wait for the next one — "are you sure?", a form with three questions, a hangman where everybody types letters, a quiz answered by replying to the question.
+
+```js
+const { createAsk } = require("morpho-socket/ask")
+const ask = createAsk({ timeoutMs: 60_000 })
+```
+
+## 1. Wire it once, before the commands
+
+```js
+listen("messages.upsert", async ({ type, messages }) => {
+  for (const msg of messages) {
+    const g = await contexts.build({ sock, msg, clientId: sessionId })
+    if (await ask.route(g)) continue          // a listener took this message: it is not a command
+    await commands.dispatch(g, { /* … */ })
+  }
+})
+```
+
+Optional sugar, so commands can write `g.ask(…)` — put it in `createContext`'s `extend`:
+
+```js
+extend: { ask(opts) { return ask.next(this, opts) } }
+```
+
+## 2. Wait for the next message of a person — `next`
+
+```js
+await g.reply("Delete everything? (yes/no)")
+const a = await ask.next(g, { match: x => /^(yes|no)$/i.test(x.text), timeoutMs: 30_000 })
+if (!a.ok) return g.reply("Time's up.")       // a.reason: "timeout" | "cancelled" | "replaced"
+if (/^yes$/i.test(a.text)) await wipe()
+await a.g.reply("Done")                        // a.g is the context of the ANSWER
+```
+
+A wizard is just several `next` in a row — pass the previous answer's `g` or the same one:
+
+```js
+const name = await ask.next(g)
+const age  = await ask.next(name.g)
+```
+
+By default `next` waits for the **same person** (`from: "sender"`), and a new question from that person replaces the old one.
+
+## 3. Many messages, many people — `open`
+
+A listener sits on a chat and receives messages until you close it or it goes idle. Your state lives in `data`.
+
+```js
+ask.open(g, {
+  key: "hangman",                                  // one per chat; a second open returns { ok: false, reason: "already-open" }
+  from: "anyone",                                  // or [numbers], or (g, listener) => boolean
+  timeoutMs: 10 * 60_000,                          // INACTIVITY: each consumed message renews it
+  data: { word: "banana", right: [], wrong: [] },
+  onMessage: async (g, l) => {
+    if (!/^[a-z]$/i.test(g.text)) return false     // false = "not for me": the message goes on to chat, commands, other listeners
+    play(l.data, g.text.toLowerCase())             // any other result = consumed
+    await g.reply(board(l.data))
+    if (finished(l.data)) l.close()
+  },
+  onClose: (l, why) => why === "timeout" && g.send(g.chatId, "Nobody answered. Game over."),
+})
+```
+
+- `from: [a, b]` makes a two-player game; `from: (g) => g.user.number === turn` gives "only whose turn it is".
+- `replyTo: sent.key.id` accepts only messages that **quote** that message — a quiz:
+
+```js
+const sent = await g.reply("Capital of Brazil?")
+ask.open(g, {
+  replyTo: sent.key.id, timeoutMs: 30_000, idle: false,     // idle: false = fixed deadline
+  onMessage: async (g2, l) => { l.close(); await g2.reply(/bras[ií]lia/i.test(g2.text) ? "Correct!" : "Nope.") },
+})
+```
+
+## Rules
+
+- **Commands are never routed to listeners**, so `!cancel` or `!forca quit` keep working in the middle of a conversation. Pass `commands: true` if a listener wants them.
+- **Per client and chat.** Several listeners can be open at once; the oldest that matches takes the message, and `false` hands it to the next one.
+- **Expected outcomes are values**: `{ ok: false, reason }`. Wrong usage (no `onMessage`, `timeoutMs <= 0`, a bad `from`) throws `TypeError`. A throwing `onMessage` still consumes the message and goes to `log`; it never breaks `route()`.
+- **In memory, on purpose.** A pending promise can't survive a restart. If a game must not be lost, keep its state in [`kv`](../kv) and open the listener again from it when the player comes back. For a request that must survive, see [`pending`](../pending).
+
+## API
+
+| | |
+|---|---|
+| `createAsk({ timeoutMs = 60 s, maxPerChat = 20, now?, timers?, log? })` | |
+| `route(g)` → `Promise<boolean>` | `true` = consumed. Call it for every message, before the commands |
+| `next(g, opts?)` → `{ ok: true, g, text }` · `{ ok: false, reason }` | `opts`: `from` (default `"sender"`), `match`, `replyTo`, `commands`, `timeoutMs`, `key` |
+| `open(g, opts)` → `{ ok: true, listener }` · `{ ok: false, reason }` | `reason`: `"already-open"` (+ `listener`) · `"too-many"` · `"unknown-sender"` |
+| `get(g, key)` · `list(g)` · `cancel(g, key)` · `clear(g?)` · `size` | `clear()` with no argument closes everything |
+
+`open` options: `key` · `from` · `match(g, listener)` · `replyTo` · `commands` · `timeoutMs` · `idle` (default `true`) · `data` · `onMessage(g, listener)` · `onClose(listener, reason)` · `replace`.
+
+A **listener** is `{ id, key, data, from, expiresAt, closed, close(reason?), touch(ms?) }`. `onClose` receives `"timeout"`, `"closed"`, `"cancelled"`, `"replaced"` (or `"answered"` for `next`).
+
+`g` is the context from [`context`](../context); `ask` only needs `g.clientId`, `g.chatId`, `g.user.number`, `g.text`, and optionally `g.command` and `g.quoted.id`.

package/packages/ask/index.js

@@ -0,0 +1,183 @@
+// @morpho/ask
+//
+// Conversations that take more than one message. Commands answer ONE message; sometimes you need to wait for the next one:
+// "are you sure?", a form with three questions, a hangman where everybody types letters, a quiz answered by replying.
+//
+//   const ask = createAsk({ timeoutMs: 60_000 })
+//
+//   // 1) wiring — once, for every message, BEFORE the commands
+//   const g = await contexts.build({ sock, msg, clientId })
+//   if (await ask.route(g)) continue                    // a listener took it: don't run it as a command
+//   await commands.dispatch(g, { ... })
+//
+//   // 2) inside a command: wait for the next message of the same person
+//   await g.reply("Delete everything? (yes/no)")
+//   const a = await ask.next(g, { match: x => /^(yes|no)$/i.test(x.text) })
+//   if (!a.ok) return g.reply("Time's up.")             // a.reason: "timeout" | "cancelled" | "replaced"
+//   if (/^yes$/i.test(a.text)) { ... }                  // a.g is the context of the answer: a.g.reply(...) works
+//
+//   // 3) many messages, many people: open a listener on the chat
+//   ask.open(g, {
+//     key: "hangman", from: "anyone", timeoutMs: 10 * 60_000,
+//     data: { word: "banana", right: [], wrong: [] },   // your state, kept on the listener
+//     onMessage: async (g, l) => {
+//       if (!/^[a-z]$/i.test(g.text)) return false      // false = "not for me": the message goes on (chat, commands, other listeners)
+//       ...                                             // anything else = consumed
+//       if (finished) l.close()
+//     },
+//     onClose: (l, why) => why === "timeout" && send("Game over: nobody answered"),
+//   })
+//
+//   // reply-to-answer (a quiz): only messages that quote the question
+//   const sent = await g.reply("Capital of Brazil?")
+//   ask.open(g, { replyTo: sent.key.id, timeoutMs: 30_000, idle: false, onMessage: ... })
+//
+// Rules
+//   - A message that is a COMMAND (g.command) is never routed to listeners unless you pass commands: true,
+//     so "!cancel" or "!forca quit" keep working in the middle of a conversation.
+//   - Listeners are per client and chat. Several can be open at once; the first that matches (oldest first) consumes the message.
+//   - Time is INACTIVITY: each consumed message renews it (idle: false = fixed deadline from the start).
+//   - Expected outcomes are values: { ok: false, reason }. Wrong usage throws TypeError.
+//   - In memory on purpose: a promise can't survive a restart. Keep game state you must not lose in @morpho/kv and re-open
+//     the listener from it when the user comes back.
+
+const DEFAULT_TIMEOUT_MS = 60_000
+let seq = 0
+
+function createAsk({ timeoutMs = DEFAULT_TIMEOUT_MS, maxPerChat = 20, now = Date.now, timers = {}, log = () => {} } = {}) {
+  if (!(timeoutMs > 0)) throw new TypeError("ask: timeoutMs must be a positive number")
+  const setT = timers.set || ((fn, ms) => { const t = setTimeout(fn, ms); t.unref?.(); return t })
+  const clearT = timers.clear || (t => clearTimeout(t))
+  const chats = new Map()                                            // "clientId/chatId" -> [listener]
+
+  const chatKey = g => {
+    if (!g || g.clientId == null || !g.chatId) throw new TypeError("ask: pass the g from @morpho/context (needs clientId and chatId)")
+    return `${g.clientId}/${g.chatId}`
+  }
+  const numberOf = g => g?.user?.number ?? null
+  const toMs = (v, name) => { if (!(v > 0) || !Number.isFinite(v)) throw new TypeError(`ask: ${name} must be a positive number (ms)`); return v }
+
+  function finish(l, reason) {
+    if (l.closed) return false
+    l.closed = true
+    clearT(l._timer)
+    const list = chats.get(l._chat)
+    if (list) { const i = list.indexOf(l); if (i >= 0) list.splice(i, 1); if (!list.length) chats.delete(l._chat) }
+    try { l.onClose?.(l, reason) } catch (e) { log("close-error", e) }
+    return true
+  }
+  function arm(l, ms) {
+    clearT(l._timer)
+    l._ms = ms
+    l.expiresAt = now() + ms
+    l._timer = setT(() => finish(l, "timeout"), ms)
+  }
+
+  function matchFrom(l, g) {
+    const f = l.from
+    if (f === "anyone" || f == null) return true
+    const n = numberOf(g)
+    if (Array.isArray(f)) return n != null && f.map(String).includes(String(n))
+    if (typeof f === "function") return !!f(g, l)
+    return false
+  }
+  async function matches(l, g) {
+    if (!l.commands && g.command) return false
+    if (!matchFrom(l, g)) return false
+    if (l.replyTo != null) {
+      const id = g.quoted?.id ?? null
+      const ok = typeof l.replyTo === "function" ? !!l.replyTo(id) : [].concat(l.replyTo).includes(id)
+      if (!ok) return false
+    }
+    if (l.match && !(await l.match(g, l))) return false
+    return true
+  }
+
+  const api = {
+    // opts: { key, from: "anyone" | "sender" | [numbers] | (g, l) => bool, match(g, l), replyTo, commands = false,
+    //         timeoutMs, idle = true, data, onMessage(g, l), onClose(l, reason), replace = false }
+    // -> { ok: true, listener } | { ok: false, reason: "already-open" | "too-many" | "unknown-sender", listener? }
+    open(g, opts = {}) {
+      const ck = chatKey(g)
+      const { key, from = "anyone", match, replyTo, commands = false, idle = true, data = null, onMessage, onClose, replace = false } = opts
+      if (typeof onMessage !== "function") throw new TypeError("ask.open: pass onMessage(g, listener)")
+      const ms = toMs(opts.timeoutMs ?? timeoutMs, "timeoutMs")
+      if (key !== undefined && (typeof key !== "string" || !key)) throw new TypeError("ask.open: key must be a non-empty string")
+
+      let fromList = from
+      if (from === "sender") {
+        const n = numberOf(g)
+        if (n == null) return { ok: false, reason: "unknown-sender" }
+        fromList = [String(n)]
+      } else if (!(from === "anyone" || Array.isArray(from) || typeof from === "function")) {
+        throw new TypeError('ask.open: from must be "anyone", "sender", an array of numbers or a function')
+      }
+
+      const list = chats.get(ck) || []
+      const existing = key !== undefined ? list.find(x => x.key === key) : null
+      if (existing && !replace) return { ok: false, reason: "already-open", listener: existing }
+      if (!existing && list.length >= maxPerChat) return { ok: false, reason: "too-many" }
+      if (existing) finish(existing, "replaced")
+
+      const l = {
+        id: ++seq, key: key ?? null, data, from: fromList, match, replyTo, commands, idle, onMessage, onClose,
+        closed: false, expiresAt: 0, _chat: ck, _timer: null, _ms: ms,
+        close(reason = "closed") { return finish(l, reason) },
+        touch(extra) { if (!l.closed) arm(l, extra === undefined ? l._ms : toMs(extra, "touch")) },
+      }
+      const fresh = chats.get(ck) || []
+      fresh.push(l); chats.set(ck, fresh)
+      arm(l, ms)
+      return { ok: true, listener: l }
+    },
+
+    // wait for ONE message. opts: as open() (from defaults to "sender"; key defaults to "next:<number>" so a new question
+    // from the same person replaces the old one). -> { ok: true, g, text } | { ok: false, reason: "timeout" | "cancelled" | "replaced" | ... }
+    next(g, opts = {}) {
+      const { onMessage, onClose, data, ...rest } = opts
+      const from = rest.from ?? "sender"
+      const key = rest.key ?? (from === "sender" ? `next:${numberOf(g)}` : undefined)
+      return new Promise(resolve => {
+        const r = api.open(g, {
+          ...rest, from, key, replace: rest.replace ?? true,
+          onMessage: (gg, l) => { l.close("answered"); resolve({ ok: true, g: gg, text: gg.text ?? "" }) },
+          onClose: (l, why) => { if (why !== "answered") resolve({ ok: false, reason: why === "closed" ? "cancelled" : why }) },
+        })
+        if (!r.ok) resolve({ ok: false, reason: r.reason })
+      })
+    },
+
+    // call this for every message BEFORE the commands. true = a listener consumed it.
+    async route(g) {
+      const list = chats.get(chatKey(g))
+      if (!list) return false
+      for (const l of [...list]) {
+        if (l.closed) continue
+        if (l.expiresAt <= now()) { finish(l, "timeout"); continue }   // the timer was late: expire here too
+        let ok = false
+        try { ok = await matches(l, g) } catch (e) { log("match-error", e); continue }
+        if (!ok || l.closed) continue
+        if (l.idle) arm(l, l._ms)
+        let r
+        try { r = await l.onMessage(g, l) } catch (e) { log("handler-error", e); r = true }   // a broken handler still consumed it
+        if (r !== false) return true
+      }
+      return false
+    },
+
+    get(g, key) { return (chats.get(chatKey(g)) || []).find(l => l.key === key) || null },
+    list(g) { return [...(chats.get(chatKey(g)) || [])] },
+    cancel(g, key) { const l = api.get(g, key); return l ? finish(l, "cancelled") : false },
+    // close every listener of a chat (or of everything, with no argument). Returns how many.
+    clear(g) {
+      const lists = g === undefined ? [...chats.values()] : [chats.get(chatKey(g)) || []]
+      let n = 0
+      for (const list of lists) for (const l of [...list]) if (finish(l, "cancelled")) n++
+      return n
+    },
+    get size() { let n = 0; for (const list of chats.values()) n += list.length; return n },
+  }
+  return api
+}
+
+module.exports = { createAsk, DEFAULT_TIMEOUT_MS }

package/packages/ask/package.json

@@ -0,0 +1 @@
+{ "name": "@morpho/ask", "version": "0.1.0", "description": "Multi-step conversations: wait for the next message of a person, or open a listener on a chat (games, wizards, confirmations, reply-to-answer). Routes before commands; ignores command messages by default; expires by inactivity.", "main": "index.js", "license": "MIT" }

package/packages/capture/README.md

@@ -0,0 +1,49 @@
+# morpho-socket/capture
+
+A **capture tool** for what Baileys delivers. When WhatsApp changes something (like the move to `@lid`), you see it here first, as an alert, before a bot notices.
+
+```js
+const { createCapture } = require("morpho-socket/capture")
+
+const capture = createCapture({ dir: "./capture" })   // writes ./capture/capture.ndjson (+ one rotated file)
+capture.attachPool(pool)                              // follows every (re)connection of the pool
+// or, without the pool:  const detach = capture.attach(sock, { sessionId: "main" })
+
+console.log(capture.reportText())                     // counts, LID with/without number, alerts
+capture.exportFixtures("./test/fixtures/baileys.json")
+```
+
+## What it records
+
+| Source | How | What is kept |
+|---|---|---|
+| Events (`messages.upsert`, `messages.update`, `lid-mapping.update`, `group-participants.update`, `groups.*`, `contacts.*`, `connection.update`, `call`) | `sock.ev.on` | the **shape**: keys, JIDs (masked), message type, enum-like fields |
+| Raw nodes (`message`, `notification`, `call`) | `sock.ws.on("frame")`, every decoded node before Baileys interprets it | tag, attributes (JIDs masked), children, binary payloads as `<bin:N>` |
+
+Outgoing nodes are not captured: Baileys sends them through an internal function that cannot be hooked from outside, and what goes on the wire is encrypted anyway.
+
+## Alerts
+
+- `lid_without_number` (warn): a `@lid` sender arrived and the field that should carry the number (`participantAlt` in groups, `remoteJidAlt` in private) is missing.
+- `frame_lid_without_number` (warn): the same, one layer lower, on the raw node (`addressing_mode=lid` without `participant_pn` / `sender_pn` / `peer_recipient_pn`).
+- `new_field` (info): a field that was not in the first sample of that event showed up. After a Baileys update this is the list of what changed.
+
+Alerts also go to the console (`console: "alerts"` by default, `true` for one line per event, `false` for silence).
+
+## Privacy
+
+- Message text, push names, captions, QR codes, credentials and binary content are **never** written. Strings become `<str:N>` unless they are a JID or an enum-like field (`type`, `action`, `connection`...).
+- Numbers are masked with a keyed hash (salt in `capture/.salt`): the same number always becomes the same fake number, with the same length and JID shape, so you can still follow "who is who" and replay the fixtures through `morpho-socket/jid`.
+- Even masked, the files describe who talks to whom. Treat the folder like the media cache: keep it out of git, and delete it when you are done. Do not share the `.salt` file.
+
+## Fixtures
+
+`exportFixtures(file)` keeps up to `perShape` (default 2) samples of each distinct shape, including the ones that raised alerts. `loadFixtures(file)` reads them back. Fixtures hold identity and structure (keys, JIDs, types), not content, which is what the `jid`, `message` and `context` layers need. Use them to run the same input through the Baileys path and through the Morpho path and compare the outputs.
+
+## Rules it never breaks
+
+It never throws into the bot (every listener is wrapped; internal failures are only counted in `report().errors`), and the file is a ring: when it passes `maxBytes` (default 1 MB) it becomes `capture.1.ndjson` and a new one starts.
+
+## Options
+
+`dir`, `maxBytes`, `mask` (`false` turns masking off, only for local debugging), `events`, `frameTags`, `console`, `salt`, `baileysVersion` (read from the bot's Baileys when omitted).