morpho-socket 0.0.0-stage → 0.2.0

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.

package/packages/jid/index.js

@@ -0,0 +1,285 @@
+// @morpho/jid — camada 3 do Morpho: IDENTIDADE.
+//
+// O WhatsApp hoje identifica a mesma pessoa de dois jeitos: o número de telefone (JID "5511...@s.whatsapp.net",
+// "PN") e um identificador opaco (LID, "123...@lid") que NÃO é o telefone. Dependendo da versão do Baileys, do tipo
+// de chat e de quem é a pessoa, a mensagem chega com um ou com o outro. Esta camada devolve sempre o mesmo:
+// o número limpo, só dígitos, ou null quando de fato não dá pra descobrir (e diz de onde veio a resposta).
+//
+//   const { criarResolvedor } = require("@morpho/jid")
+//   const identidade = criarResolvedor({ store })          // store é opcional; com ele o mapa LID→número sobrevive a reinício
+//   pool.on("connect", (_id, sock) => identidade.instalar(sock))   // aprende mapeamentos que o Baileys anuncia
+//   const quem = await identidade.remetente(msg, { sock })
+//   quem.numero      // "5511968111161" | null
+//   quem.formatado   // "+55 (11) 96811-1161"
+//   quem.ehBot       // true se quem mandou foi o próprio número do bot
+//   quem.origem      // "bot" | "mensagem" | "alt" | "mapa" | "baileys" | "grupo" | null
+//
+// Sem dependência do Baileys: o que for específico dele (sock.user, signalRepository, groupMetadata) é lido do
+// `sock` que você passa, e cada fonte é opcional — se a versão do Baileys não tem, a próxima fonte é tentada.
+
+const PN_DOMAINS = new Set(["s.whatsapp.net", "c.us"])
+const LID_DOMAINS = new Set(["lid", "hosted.lid"])
+
+// JID do Baileys: usuario[_agente][:dispositivo]@dominio
+function parts(jid) {
+  if (typeof jid !== "string") return null
+  const at = jid.lastIndexOf("@")
+  if (at <= 0) return null
+  const [withAgent, device] = jid.slice(0, at).split(":")
+  const [user, agent] = withAgent.split("_")
+  return { user, agent, device, domain: jid.slice(at + 1) }
+}
+
+function kind(jid) {
+  const p = parts(jid)
+  if (!p) return null
+  if (PN_DOMAINS.has(p.domain)) return "pn"
+  if (LID_DOMAINS.has(p.domain)) return "lid"
+  if (p.domain === "g.us") return "group"
+  if (p.domain === "broadcast") return "broadcast"
+  if (p.domain === "newsletter") return "newsletter"
+  return "other"
+}
+
+// tira dispositivo e agente: "5511...:12@s.whatsapp.net" -> "5511...@s.whatsapp.net"
+function normalize(jid) {
+  const p = parts(jid)
+  if (!p) return null
+  return `${p.user}@${p.domain === "c.us" ? "s.whatsapp.net" : p.domain}`
+}
+
+// só dígitos. Aceita JID de telefone ou uma string de número. LID, grupo etc. NÃO viram número (devolve null).
+function digits(value) {
+  if (typeof value !== "string" || !value) return null
+  if (value.includes("@")) {
+    if (kind(value) !== "pn") return null
+    const u = parts(value).user
+    return /^\d{8,15}$/.test(u) ? u : null
+  }
+  const d = value.replace(/\D/g, "")
+  return d.length >= 8 && d.length <= 15 ? d : null
+}
+
+// "5511968111161" -> "+55 (11) 96811-1161" (Brasil); outros países: "+<dígitos>"
+function formatNumber(d) {
+  if (!d) return null
+  const br = /^55(\d{2})(\d{8,9})$/.exec(d)
+  if (!br) return `+${d}`
+  const rest = br[2]
+  return `+55 (${br[1]}) ${rest.slice(0, rest.length - 4)}-${rest.slice(-4)}`
+}
+
+function createResolver({ store, warmUpIntervalMs = 120000 } = {}) {
+  const memory = new Map() // "123@lid" -> "5511..." (só dígitos)
+  const lidKey = lid => (kind(lid) === "lid" ? normalize(lid) : null)
+
+  // guarda o par LID↔número (memória + store, se o store souber guardar). Devolve true se aprendeu algo novo.
+  function learn(lid, pn) {
+    const k = lidKey(lid)
+    const d = digits(pn)
+    if (!k || !d || memory.get(k) === d) return false
+    memory.set(k, d)
+    try { store?.setLid?.(k, d) } catch { /* guardar é bônus: não pode derrubar a mensagem */ }
+    return true
+  }
+
+  async function remembered(k) {
+    if (memory.has(k)) return memory.get(k)
+    let d = null
+    try { d = await store?.getLid?.(k) } catch { /* idem */ }
+    if (d) memory.set(k, d)
+    return d || null
+  }
+
+  // o Baileys 7 já manda o "par" do JID na própria chave da mensagem (remoteJidAlt / participantAlt): aproveita sempre
+  function learnFrom(msg) {
+    const k = msg?.key || {}
+    for (const [a, b] of [[k.remoteJid, k.remoteJidAlt], [k.participant, k.participantAlt]]) {
+      if (kind(a) === "lid") learn(a, b)
+      else if (kind(b) === "lid") learn(b, a)
+    }
+  }
+
+  // lista de participantes de UM grupo: cada membro traz os dois ids (LID e telefone). Devolve quantos pares novos aprendeu.
+  function learnGroup(meta) {
+    let added = 0
+    for (const p of meta?.participants || []) {
+      const ids = [p.id, p.lid, p.phoneNumber, p.jid].filter(x => typeof x === "string")
+      const l = ids.find(x => kind(x) === "lid")
+      const n = ids.find(x => kind(x) === "pn")
+      if (l && n && learn(l, n)) added++
+    }
+    return added
+  }
+
+  // O mapa LID→número que vale pro grupo vale pro PRIVADO também: quem está num grupo com o bot, o bot já "conhece".
+  // Então, em vez de esperar a pessoa falar num grupo, lê TODOS os grupos do bot de uma vez (1 consulta) e aprende todo mundo.
+  // Com intervalo mínimo entre consultas, pra não pesar no WhatsApp (e pra um LID sem solução não disparar uma por mensagem).
+  let lastWarmUp = 0
+  let warming = null
+  function warmUp(sock, { force = false } = {}) {
+    if (typeof sock?.groupFetchAllParticipating !== "function") return Promise.resolve(0)
+    if (warming) return warming
+    if (!force && Date.now() - lastWarmUp < warmUpIntervalMs) return Promise.resolve(0)
+    lastWarmUp = Date.now()
+    warming = (async () => {
+      try {
+        let added = 0
+        for (const meta of Object.values((await sock.groupFetchAllParticipating()) || {})) added += learnGroup(meta)
+        return added
+      } catch { return 0 } finally { warming = null }
+    })()
+    return warming
+  }
+
+  function learnContact(c) {
+    if (!c) return
+    learn(c.lid, c.phoneNumber || c.pn)
+    if (kind(c.id) === "pn") learn(c.lid, c.id)
+    else if (kind(c.id) === "lid") learn(c.id, c.phoneNumber || c.pn)
+  }
+
+  // liga o resolvedor nos eventos do socket que anunciam mapeamentos. Chame a cada (re)conexão: o socket é novo.
+  function install(sock) {
+    const ev = sock?.ev
+    if (!ev?.on) return
+    ev.on("lid-mapping.update", u => learn(u?.lid, u?.pn))
+    const contacts = list => { for (const c of list || []) learnContact(c) }
+    ev.on("contacts.upsert", contacts)
+    ev.on("contacts.update", contacts)
+    ev.on("groups.upsert", list => { for (const m of list || []) learnGroup(m) })
+    ev.on("group-participants.update", u => { // participants vem como texto (Baileys 6) ou como objetos {id, phoneNumber} (7)
+      for (const p of u?.participants || []) if (p && typeof p === "object") learnGroup({ participants: [p] })
+    })
+  }
+
+  // LID -> número, tentando as fontes da mais barata pra mais cara.
+  async function resolveLid(lid, { sock, group } = {}) {
+    const k = lidKey(lid)
+    if (!k) return null
+
+    const stored = await remembered(k)
+    if (stored) return { number: stored, source: "map" }
+
+    const repo = sock?.signalRepository?.lidMapping // existe no Baileys 7
+    if (typeof repo?.getPNForLID === "function") {
+      try {
+        const pn = await repo.getPNForLID(k)
+        const d = digits(pn)
+        if (d) { learn(k, pn); return { number: d, source: "baileys" } }
+      } catch { /* próxima fonte */ }
+    }
+
+    // em grupo, a lista de participantes traz os dois ids de cada um: aprende o grupo inteiro de uma vez
+    if (kind(group) === "group" && typeof sock?.groupMetadata === "function") {
+      try {
+        learnGroup(await sock.groupMetadata(group))
+        const d = memory.get(k)
+        if (d) return { number: d, source: "group" }
+      } catch { /* sem metadata: tenta a próxima fonte */ }
+    }
+
+    // privado (ou grupo que não adiantou): pergunta por todos os grupos do bot
+    await warmUp(sock)
+    const d = memory.get(k)
+    if (d) return { number: d, source: "groups" }
+    return null
+  }
+
+  // Quem mandou esta mensagem? (em grupo: o participante; no privado: o dono do chat; fromMe: o próprio bot)
+  async function sender(msg, { sock } = {}) {
+    const key = msg?.key || {}
+    const group = kind(key.remoteJid) === "group" ? key.remoteJid : null
+    const myPn = sock?.user?.id
+    const myLid = sock?.user?.lid
+    const botNumber = digits(myPn)
+    learnFrom(msg)
+
+    const finish = o => {
+      const number = o.number || null
+      return {
+        group, isBot: false, jid: null, lid: null, source: null, ...o,
+        pn: number ? `${number}@s.whatsapp.net` : null,
+        number, formatted: formatNumber(number), resolved: !!number
+      }
+    }
+    const bot = () => finish({ isBot: true, jid: myPn || key.participant || key.remoteJid || null, lid: normalize(myLid) || null, number: botNumber, source: "bot" })
+
+    if (key.fromMe) return bot()
+
+    const raw = group ? key.participant : key.remoteJid
+    if (!raw) return finish({})
+    if ([myPn, myLid].some(x => x && normalize(x) === normalize(raw))) return bot()
+
+    const t = kind(raw)
+    if (t === "pn") return finish({ jid: raw, number: digits(raw), source: "message" })
+    if (t === "lid") {
+      const alt = group ? key.participantAlt : key.remoteJidAlt
+      let number = kind(alt) === "pn" ? digits(alt) : null
+      let source = number ? "alt" : null
+      if (!number) { const r = await resolveLid(raw, { sock, group }); if (r) ({ number, source } = r) }
+      return finish({ jid: raw, lid: normalize(raw), number, source })
+    }
+    return finish({ jid: raw })
+  }
+
+  return { sender, resolveLid, learn, learnFrom, learnGroup, warmUp, install }
+}
+
+// ---------------------------------------------------------------------------------------------
+// createIdentity: ONE service for a multi-client bot. A resolver per client (the warm-up that reads all groups is per bot
+// number), all sharing the same store (a person's LID is the same for every bot). Never throws: if resolving fails, the
+// message must NOT be lost because of identity, so it falls back to what came in the message.
+//
+//   const identity = createIdentity({ store })
+//   identity.install(sock, clientId)                                   // on every (re)connection
+//   const who = await identity.resolveSender(msg, sock, clientId)      // { number, formatted, pn, jid, lid, isBot, source, resolved, group }
+//   const r = await identity.resolveJid(jid, { sock, clientId, group }) // { number, source } | null
+// ---------------------------------------------------------------------------------------------
+function createIdentity({ store, warmUpIntervalMs } = {}) {
+  const resolvers = new Map()
+  const forClient = (clientId = "default") => {
+    let r = resolvers.get(clientId)
+    if (!r) { r = createResolver({ store, warmUpIntervalMs }); resolvers.set(clientId, r) }
+    return r
+  }
+
+  function fallback(msg, sock) {
+    const k = msg?.key || {}
+    const jid = k.fromMe ? sock?.user?.id : ((k.remoteJid || "").endsWith("@g.us") ? k.participant : k.remoteJid)
+    const number = digits(jid || "")
+    return {
+      number, formatted: null, pn: number ? `${number}@s.whatsapp.net` : null, jid: jid || null,
+      lid: kind(jid) === "lid" ? normalize(jid) : null, isBot: !!k.fromMe, source: null, resolved: !!number, group: null
+    }
+  }
+
+  async function resolveSender(msg, sock, clientId) {
+    try { return await forClient(clientId).sender(msg, { sock }) }
+    catch (e) { return fallback(msg, sock) }
+  }
+
+  async function resolveJid(jid, { sock, clientId, group } = {}) {
+    if (!jid) return null
+    const t = kind(jid)
+    if (t === "pn") { const number = digits(jid); return number ? { number, source: "message" } : null }
+    if (t !== "lid") return null
+    try { const r = await forClient(clientId).resolveLid(jid, { sock, group }); return r ? { number: r.number, source: r.source } : null }
+    catch { return null }
+  }
+
+  // learns from the groups ALREADY fetched (sock.groupFetchAllParticipating()): no extra query
+  function learnGroups(clientId, groups) {
+    let learned = 0
+    for (const meta of Object.values(groups || {})) learned += forClient(clientId).learnGroup(meta)
+    return learned
+  }
+
+  return {
+    forClient, resolveSender, resolveJid, learnGroups, fallback,
+    install: (sock, clientId) => forClient(clientId).install(sock),
+    warmUp: (sock, clientId, opts = { force: true }) => forClient(clientId).warmUp(sock, opts)
+  }
+}
+
+module.exports = { createIdentity, createResolver, parts, kind, normalize, digits, formatNumber }

package/packages/jid/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@morpho/jid",
+  "version": "0.1.0",
+  "description": "Identidade no Morpho: descobre o número limpo (só dígitos) de quem mandou a mensagem, resolvendo @lid para número de telefone, e lembra o mapa LID→número.",
+  "main": "index.js",
+  "license": "MIT"
+}

package/packages/kv/README.md

@@ -0,0 +1,45 @@
+# morpho-socket/kv
+
+Where your bot's **data** lives — economy, group settings, cooldowns — in a single SQLite file, with no dependency (`node:sqlite`, Node ≥ 22.5).
+
+Instead of "one JSON file per thing plus a delayed write", every write is on disk when the call returns, and several writes can be **all-or-nothing**.
+
+```js
+const { openKV, DELETE } = require("morpho-socket/kv")
+const db  = openKV("data/bot.sqlite")             // ":memory:" in tests
+const eco = db.collection("economy")              // a named drawer: string keys → any JSON
+
+eco.set("5511999", { coins: 10 })
+eco.get("5511999")                                // { coins: 10 }  (get(key, fallback) when it doesn't exist)
+eco.update("5511999", u => ({ ...u, coins: u.coins + 5 }), { coins: 0 })   // atomic read-modify-write
+eco.incr("counter")                               // number += 1
+```
+
+## Transfers without losing anything
+
+```js
+db.transaction(() => {                            // if anything throws in here, NOTHING is written
+  eco.update(from, u => { if (u.coins < n) throw new Error("insufficient funds"); return { ...u, coins: u.coins - n } })
+  eco.update(to,   u => ({ ...u, coins: u.coins + n }))
+})
+```
+
+The transaction function is **synchronous on purpose** (an `async` one is rejected): SQLite is a local file, calls take microseconds, and the absence of `await` is what guarantees nobody touches the data in the middle. Nested transactions become savepoints.
+
+## Everything else
+
+| | |
+|---|---|
+| read | `get(k, fallback)` `has(k)` `keys(prefix?)` `entries(prefix?)` `values(prefix?)` `count(prefix?)` `toObject(prefix?)` |
+| write | `set(k, v, { ttl })` `update(k, fn, initial)` `incr(k, n)` `delete(k)` `setMany(object \| pairs)` `clear(prefix?)` |
+| expiry | `set(k, v, { ttl: ms })` — disappears by itself (a `/daily` cooldown, a cache). `update` keeps the original expiry; a plain `set` resets it |
+| ranking | `top("coins", { limit: 10, prefix, order: "desc" })` → `[[key, value], …]` (accepts `"stats.wins"`; ignores entries without the field) |
+| scope | `groups.sub(clientId, groupId)` → an isolated drawer: keys become `clientId/groupId/…`, so one client never sees another's data |
+| database | `db.stats()` `db.collections()` `db.sweep()` `db.backup("copy.sqlite")` `db.close()` |
+
+- `undefined` can't be stored (use `delete`, or `null`). In `update`, return the new value, or `DELETE` to remove the key.
+- Two processes on the same file (bot + dashboard) see each other immediately (WAL mode, waits up to 5 s on a lock).
+- `backup()` makes a consistent copy while the bot is running; it fails if the target file already exists.
+- Importing old JSON files: `eco.setMany(JSON.parse(fs.readFileSync("economy.json", "utf8")))` (all-or-nothing).
+
+`node:sqlite` prints an `ExperimentalWarning` on current Node versions; it is harmless.

package/packages/kv/index.js

@@ -0,0 +1,164 @@
+// @morpho/kv — where the bot's DATA lives (economy, groups' settings, cooldowns...): one SQLite file, zero dependencies
+// (node:sqlite, Node >= 22.5). Replaces "a JSON per thing + a 3-second debounce": every write is on disk when the call
+// returns, and several writes can be ALL-or-NOTHING.
+//
+//   const { openKV, DELETE } = require("@morpho/kv")
+//   const db = openKV("data/morvyn.sqlite")                  // ":memory:" for tests
+//   const eco = db.collection("economy")                      // a named drawer: keys are strings, values are anything JSON
+//
+//   eco.set("5511999", { coins: 10 });  eco.get("5511999")    // -> { coins: 10 }      (get(key, fallback) for a default)
+//   eco.update("5511999", u => ({ ...u, coins: u.coins + 5 }), { coins: 0 })        // read-modify-write, atomic
+//
+//   db.transaction(() => {                                     // ALL-or-NOTHING (throw = everything is undone)
+//     eco.update(from, u => ({ ...u, coins: u.coins - 50 }))
+//     eco.update(to,   u => ({ ...u, coins: u.coins + 50 }))
+//   })
+//
+//   const grupo = db.collection("groups").sub(clientId, groupId)   // scoped: keys become "clientId/groupId/..." (client isolation)
+//   cooldowns.set(`${user}:daily`, true, { ttl: 24 * 3600e3 })      // expires by itself (get/has/keys never see it afterwards)
+//   eco.top("coins", { limit: 10 })                                 // ranking by a field of the JSON value
+//
+// Sync on purpose: SQLite here is a local file, calls take microseconds, and "no await" is what makes a transaction safe.
+const { DatabaseSync } = require("node:sqlite")
+
+const DELETE = Symbol("morpho.kv.delete")      // return it from update() to remove the key
+const PATH = /^[A-Za-z_][\w]*(\.[A-Za-z_][\w]*|\[\d+\])*$/   // field paths for top(): "coins", "stats.wins"
+
+const keyOf = k => {
+  if (typeof k === "number" && Number.isFinite(k)) k = String(k)
+  if (typeof k !== "string" || !k) throw new TypeError("kv: key must be a non-empty string")
+  return k
+}
+const encode = v => {
+  if (v === undefined) throw new TypeError("kv: undefined can't be stored (use delete(), or null)")
+  const s = JSON.stringify(v)
+  if (s === undefined) throw new TypeError("kv: value is not JSON-serializable")
+  return s
+}
+// every key that starts with `prefix` is in [prefix, prefix + U+10FFFF)   (BINARY collation compares UTF-8 bytes)
+const range = prefix => [prefix, prefix + "\u{10FFFF}"]
+
+function openKV(path = ":memory:", { now = Date.now, sweepEveryMs = 10 * 60_000, busyTimeoutMs = 5000 } = {}) {
+  const sql = new DatabaseSync(path)
+  sql.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = NORMAL;
+    PRAGMA busy_timeout = ${Number(busyTimeoutMs) | 0};
+    CREATE TABLE IF NOT EXISTS kv (
+      col   TEXT NOT NULL,
+      key   TEXT NOT NULL,
+      value TEXT NOT NULL,
+      exp   INTEGER,                         -- NULL = never expires; else epoch ms
+      PRIMARY KEY (col, key)
+    ) WITHOUT ROWID;
+    CREATE INDEX IF NOT EXISTS kv_exp ON kv (exp) WHERE exp IS NOT NULL;
+  `)
+
+  const cache = new Map()
+  const stmt = q => { let s = cache.get(q); if (!s) cache.set(q, s = sql.prepare(q)); return s }
+  const live = "(exp IS NULL OR exp > ?)"
+
+  // ----- transactions (nest = savepoints) -----
+  let depth = 0
+  function transaction(fn) {
+    if (typeof fn !== "function") throw new TypeError("kv.transaction: pass a function")
+    const name = `sp${depth}`
+    sql.exec(depth === 0 ? "BEGIN IMMEDIATE" : `SAVEPOINT ${name}`)
+    depth++
+    let result
+    try {
+      result = fn()
+      if (result && typeof result.then === "function") throw new TypeError("kv.transaction: the function must be synchronous (no await inside: SQLite is sync, and an open transaction can't wait)")
+    } catch (e) {
+      depth--
+      sql.exec(depth === 0 ? "ROLLBACK" : `ROLLBACK TO ${name}; RELEASE ${name}`)
+      throw e
+    }
+    depth--
+    sql.exec(depth === 0 ? "COMMIT" : `RELEASE ${name}`)
+    return result
+  }
+
+  function sweep() { return Number(stmt("DELETE FROM kv WHERE exp IS NOT NULL AND exp <= ?").run(now()).changes) }
+  const timer = sweepEveryMs ? setInterval(() => { try { sweep() } catch {} }, sweepEveryMs) : null
+  timer?.unref?.()
+
+  // a "drawer": one collection, optionally scoped by a key prefix
+  function makeCollection(col, scope = "") {
+    const K = k => scope + keyOf(k)
+    const unK = k => k.slice(scope.length)
+    const pre = (prefix = "") => range(scope + prefix)
+    const api = {
+      name: col, scope,
+
+      get(key, fallback) {
+        const r = stmt(`SELECT value FROM kv WHERE col = ? AND key = ? AND ${live}`).get(col, K(key), now())
+        return r ? JSON.parse(r.value) : fallback
+      },
+      has(key) { return !!stmt(`SELECT 1 x FROM kv WHERE col = ? AND key = ? AND ${live}`).get(col, K(key), now()) },
+      // opts: { ttl: ms }  -> expires after that long (a plain set() clears any previous expiry)
+      set(key, value, { ttl } = {}) {
+        const exp = ttl === undefined || ttl === null ? null : now() + Number(ttl)
+        if (exp !== null && !Number.isFinite(exp)) throw new TypeError("kv.set: ttl must be a number (ms)")
+        stmt("INSERT INTO kv (col, key, value, exp) VALUES (?, ?, ?, ?) ON CONFLICT(col, key) DO UPDATE SET value = excluded.value, exp = excluded.exp")
+          .run(col, K(key), encode(value), exp)
+        return value
+      },
+      // read-modify-write in ONE transaction. fn(old) must return the new value (or DELETE). `initial` is `old` when the key doesn't exist.
+      // The expiry of an existing key is kept.
+      update(key, fn, initial) {
+        return transaction(() => {
+          const r = stmt(`SELECT value, exp FROM kv WHERE col = ? AND key = ? AND ${live}`).get(col, K(key), now())
+          const next = fn(r ? JSON.parse(r.value) : initial)
+          if (next === DELETE) { stmt("DELETE FROM kv WHERE col = ? AND key = ?").run(col, K(key)); return undefined }
+          if (next === undefined) throw new TypeError("kv.update: return the new value (or DELETE to remove the key)")
+          stmt("INSERT INTO kv (col, key, value, exp) VALUES (?, ?, ?, ?) ON CONFLICT(col, key) DO UPDATE SET value = excluded.value, exp = excluded.exp")
+            .run(col, K(key), encode(next), r?.exp ?? null)
+          return next
+        })
+      },
+      // number += n (starts at 0). For objects use update().
+      incr(key, n = 1) { return api.update(key, v => { if (typeof v !== "number") throw new TypeError(`kv.incr: "${key}" holds ${typeof v}, not a number`); return v + n }, 0) },
+      delete(key) { return stmt("DELETE FROM kv WHERE col = ? AND key = ?").run(col, K(key)).changes > 0 },
+
+      keys(prefix = "") { const [a, b] = pre(prefix); return stmt(`SELECT key FROM kv WHERE col = ? AND key >= ? AND key < ? AND ${live} ORDER BY key`).all(col, a, b, now()).map(r => unK(r.key)) },
+      entries(prefix = "") { const [a, b] = pre(prefix); return stmt(`SELECT key, value FROM kv WHERE col = ? AND key >= ? AND key < ? AND ${live} ORDER BY key`).all(col, a, b, now()).map(r => [unK(r.key), JSON.parse(r.value)]) },
+      values(prefix = "") { return api.entries(prefix).map(e => e[1]) },
+      count(prefix = "") { const [a, b] = pre(prefix); return Number(stmt(`SELECT COUNT(*) n FROM kv WHERE col = ? AND key >= ? AND key < ? AND ${live}`).get(col, a, b, now()).n) },
+      toObject(prefix = "") { return Object.fromEntries(api.entries(prefix)) },
+      // many at once (all-or-nothing). Accepts { key: value } or [[key, value]]. Handy to import an old JSON file.
+      setMany(data, opts) { const list = Array.isArray(data) ? data : Object.entries(data); return transaction(() => { for (const [k, v] of list) api.set(k, v, opts); return list.length }) },
+      clear(prefix = "") { const [a, b] = pre(prefix); return Number(stmt("DELETE FROM kv WHERE col = ? AND key >= ? AND key < ?").run(col, a, b).changes) },
+
+      // ranking by a field of the JSON value: top("coins", { limit: 10, prefix, order: "desc" }) -> [[key, value], ...]
+      top(field, { limit = 10, prefix = "", order = "desc" } = {}) {
+        if (!PATH.test(field)) throw new TypeError(`kv.top: invalid field "${field}" (use "coins" or "stats.wins")`)
+        const [a, b] = pre(prefix)
+        const dir = String(order).toLowerCase() === "asc" ? "ASC" : "DESC"
+        const jp = "$." + field
+        return stmt(`SELECT key, value FROM kv WHERE col = ? AND key >= ? AND key < ? AND ${live} AND json_type(value, ?) IN ('integer','real') ORDER BY json_extract(value, ?) ${dir}, key LIMIT ?`)
+          .all(col, a, b, now(), jp, jp, Math.max(1, limit | 0)).map(r => [unK(r.key), JSON.parse(r.value)])
+      },
+
+      // a narrower drawer: keys get the parts joined by "/" as a prefix (e.g. sub(clientId, groupId))
+      sub(...parts) {
+        const p = parts.map(x => { const s = keyOf(x); if (s.includes("/")) throw new TypeError(`kv.sub: "${s}" can't contain "/"`); return s }).join("/") + "/"
+        return makeCollection(col, scope + p)
+      }
+    }
+    return api
+  }
+
+  return {
+    collection(name) { if (typeof name !== "string" || !name || name.includes("\0")) throw new TypeError("kv.collection: name must be a non-empty string"); return makeCollection(name) },
+    transaction, sweep,
+    collections() { return stmt("SELECT DISTINCT col FROM kv ORDER BY col").all().map(r => r.col) },
+    stats() { const o = {}; for (const r of stmt(`SELECT col, COUNT(*) n FROM kv WHERE ${live} GROUP BY col`).all(now())) o[r.col] = Number(r.n); return o },
+    // consistent copy of the whole database into ONE file (safe while the bot is running). Fails if the file already exists.
+    backup(file) { sql.prepare("VACUUM INTO ?").run(String(file)); return file },
+    close() { if (timer) clearInterval(timer); cache.clear(); sql.close() },
+    get raw() { return sql }
+  }
+}
+
+module.exports = { openKV, DELETE }