morpho-socket 0.0.0-stage → 0.3.0

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 }

package/packages/kv/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@morpho/kv",
+  "version": "0.1.0",
+  "description": "Dados do bot num arquivo SQLite só: coleções chave→JSON, transações (transferência de moedas sem perder nada), validade (cooldowns), ranking e backup. Sem dependência externa.",
+  "main": "index.js",
+  "engines": { "node": ">=22.5.0" },
+  "license": "MIT"
+}

package/packages/media/README.md

@@ -0,0 +1,70 @@
+# morpho-socket/media
+
+WhatsApp media download that **does not give up**. It does not depend on Baileys at import time (Baileys is loaded only when a download actually happens, and the downloader can be replaced), so it is testable without WhatsApp.
+
+```js
+const { createMedia } = require("morpho-socket/media")
+const media = createMedia({ disk: { dir: "./cache/media" } })
+
+media.bind(msg, sock)                                              // optional, see "Expired links"
+const r = await media.download(msg, { types: ["image", "video"] }) // null when there is no media
+r.buffer; r.type; r.mimetype; r.size; r.fromQuoted; r.source       // source: "memory" | "disk" | "network" | "resend"
+```
+
+## What it solves
+
+| Problem | Solution |
+|---|---|
+| Which media is it? | `find(msg, { types, quoted })`: the **replied-to** message's media wins, else the message's own. Understands view-once, ephemeral and document captions. `quoted: "only"` / `"never"` restricts it |
+| **The CDN link expired** (403/404/410) | asks the phone to re-send it (`sock.updateMediaMessage`) **once**, with a time limit (30 s), then downloads again. For a replied-to message it rebuilds the key (id, author, `fromMe`). Several requests for the same message share one |
+| Network failures | retries with a growing wait, only for network errors, 429 and 5xx (2 retries). Invalid key / failed decryption gives up at once |
+| Huge files | refused **before** downloading (declared size) and **while** downloading (bytes received); the stream is closed |
+| Stalled downloads | per-attempt timeout (45 s); the stream is closed |
+| Download bursts | at most 4 at a time, the rest queue |
+| Same media again | memory cache (LRU by **bytes**) and optional disk cache. The key is the file hash, so the same sticker re-sent by someone else is a hit. Concurrent identical requests become one |
+
+## Expired links: how it works
+
+`updateMediaMessage` needs `{ key, message }` and the **socket that received the message**. `find()` builds that pair for you. Give it the socket on each call (`download(msg, { sock })`) or once per message with `bind(msg, sock)` — handy when a command runs without the socket at hand ([`context`](../context) does the binding for you).
+
+Re-sending is **best effort**: the phone has to be online and still have the message. If it can't, the error is `MEDIA_EXPIRED`. The disk cache is the way out for heavily used media: once downloaded, it no longer depends on the link.
+
+## Privacy
+
+- **View-once media is never cached** (memory or disk) unless you set `cacheViewOnce: true`.
+- The disk cache stores **decrypted** media: directory `0700`, files `0600`, 24 h expiry and a size cap (256 MB). Keep it out of folders that get backed up or zipped.
+
+## Errors
+
+`MediaError` with a stable `code` (the original error is in `e.cause`):
+
+| `code` | Meaning |
+|---|---|
+| `MEDIA_TOO_LARGE` | over the size limit (declared or received) |
+| `MEDIA_EXPIRED` | link expired and could not be recovered (phone offline, message deleted…) |
+| `MEDIA_TIMEOUT` | took too long, even after retries |
+| `MEDIA_NETWORK` | network/server failure even after retries |
+| `MEDIA_INVALID` | message without key/URL, or content that does not decrypt (retrying won't help) |
+| `MEDIA_UNAVAILABLE` | anything else |
+
+## Options
+
+`createMedia({ … })`
+
+| Option | Default |
+|---|---|
+| `downloader(node, type)` | Baileys' `downloadContentFromMessage` |
+| `max` | 50 MB |
+| `timeoutMs` | 45 s per attempt |
+| `retries` / `backoff(n)` | 2 / 400 ms × 3ⁿ |
+| `reuploadTimeoutMs` | 30 s |
+| `concurrency` | 4 |
+| `cache` | `false`, or `{ maxBytes, maxEntry, ttlMs }` — default 64 MB / 8 MB per entry / 10 min |
+| `disk` | off; `{ dir, maxBytes, maxEntry, ttlMs }` — 256 MB / 32 MB / 24 h |
+| `cacheViewOnce` | `false` |
+| `copy` | `true` — hand out a copy of cached buffers so mutating one can't corrupt the cache |
+| `log(event, data)` | `"resend"`, `"retry"`, `"disk-cache-error"` |
+
+Methods: `find` · `download(msgOrFound, opts)` (opts: `sock`, `max`, `timeoutMs`, `cache`, `reupload`, plus `types`/`quoted`) · `downloadFound` · `prefetch(msg)` (warms the cache with something that just arrived; never throws) · `bind` · `stats()` · `clearCache()`.
+
+Also exported: `MediaError`, `classify`, `find`, `DEFAULT_MAX`, `createMemoryCache`, `createDiskCache`.