morpho-socket 0.0.0-stage → 0.2.0

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`.

package/packages/media/cache.js

@@ -0,0 +1,116 @@
+// @morpho/media — cache de mídia já decifrada. Duas camadas, ambas opcionais e independentes:
+//   memória: LRU limitado por BYTES (não por quantidade), com validade. Some ao reiniciar.
+//   disco:   sobrevive a reinício e é a que resolve de verdade o link expirado das mídias QUENTES (a figurinha que o
+//            grupo inteiro usa): baixou uma vez, não depende mais do WhatsApp. Limitado por bytes e validade.
+// Atenção: o disco guarda a mídia DECIFRADA dos usuários. Pasta com permissão só do dono (0700/0600), e fora de pastas
+// que entram em backup ou zip.
+const fs = require("fs")
+const fsp = fs.promises
+const path = require("path")
+const crypto = require("crypto")
+
+const MB = 1024 * 1024
+
+function createMemoryCache({ maxBytes = 64 * MB, maxEntry = 8 * MB, ttlMs = 10 * 60e3, now = Date.now } = {}) {
+  const items = new Map() // chave -> { buf, em } (ordem de inserção = ordem de uso: o mais antigo é o primeiro)
+  let total = 0
+
+  const remove = k => { const e = items.get(k); if (e) { total -= e.buf.length; items.delete(k) } }
+
+  return {
+    get(k) {
+      const e = items.get(k)
+      if (!e) return null
+      if (now() - e.at > ttlMs) { remove(k); return null }
+      items.delete(k); items.set(k, e) // usado agora: vai pro fim
+      return e.buf
+    },
+    set(k, buf) {
+      if (!Buffer.isBuffer(buf) || buf.length > maxEntry || buf.length > maxBytes) return false
+      remove(k)
+      while (total + buf.length > maxBytes && items.size) remove(items.keys().next().value)
+      items.set(k, { buf, at: now() }); total += buf.length
+      return true
+    },
+    clear() { items.clear(); total = 0 },
+    stats: () => ({ entries: items.size, bytes: total, maxBytes })
+  }
+}
+
+function createDiskCache({ dir, maxBytes = 256 * MB, maxEntry = 32 * MB, ttlMs = 24 * 3600e3, now = Date.now } = {}) {
+  if (!dir) throw new Error("criarCacheDisco: 'dir' é obrigatório.")
+  let total = 0
+  let ready = null
+  let cleaning = null
+
+  const file = k => path.join(dir, crypto.createHash("sha256").update(k).digest("hex").slice(0, 40) + ".bin")
+
+  // lista { f, tamanho, em } de tudo que é cache; apaga sobra de gravação interrompida (.tmp)
+  async function list() {
+    const out = []
+    for (const name of await fsp.readdir(dir).catch(() => [])) {
+      const f = path.join(dir, name)
+      if (name.endsWith(".tmp")) { await fsp.unlink(f).catch(() => {}); continue }
+      if (!name.endsWith(".bin")) continue
+      try { const s = await fsp.stat(f); out.push({ f, size: s.size, at: s.mtimeMs }) } catch { /* sumiu no meio */ }
+    }
+    return out
+  }
+
+  const start = () => ready ||= (async () => {
+    await fsp.mkdir(dir, { recursive: true, mode: 0o700 })
+    total = (await list()).reduce((a, x) => a + x.size, 0)
+  })()
+
+  // tira o vencido e, se ainda passar do limite, os menos usados (mtime = último uso: get() renova)
+  const trimExcess = () => cleaning ||= (async () => {
+    try {
+      let items = await list()
+      for (const x of items.filter(x => now() - x.at > ttlMs)) await fsp.unlink(x.f).catch(() => {})
+      items = items.filter(x => now() - x.at <= ttlMs).sort((a, b) => a.at - b.at)
+      total = items.reduce((a, x) => a + x.size, 0)
+      for (const x of items) {
+        if (total <= maxBytes * 0.9) break
+        await fsp.unlink(x.f).catch(() => {}); total -= x.size
+      }
+    } finally { cleaning = null }
+  })()
+
+  return {
+    async get(k) {
+      await start()
+      const f = file(k)
+      try {
+        const s = await fsp.stat(f)
+        if (now() - s.mtimeMs > ttlMs) { await fsp.unlink(f).catch(() => {}); total -= s.size; return null }
+        const buf = await fsp.readFile(f)
+        const t = new Date(now()); await fsp.utimes(f, t, t).catch(() => {}) // renova o "último uso"
+        return buf
+      } catch { return null }
+    },
+    async set(k, buf) {
+      if (!Buffer.isBuffer(buf) || buf.length > maxEntry || buf.length > maxBytes) return false
+      await start()
+      const f = file(k)
+      const before = await fsp.stat(f).then(s => s.size, () => 0)
+      const tmp = `${f}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`
+      try {
+        await fsp.writeFile(tmp, buf, { mode: 0o600 })
+        await fsp.rename(tmp, f) // atômico: quem lê nunca vê arquivo pela metade
+        // "último uso" gravado de propósito: gravações seguidas podem empatar no relógio do sistema de arquivos
+        const t = new Date(now()); await fsp.utimes(f, t, t)
+      } catch (e) { await fsp.unlink(tmp).catch(() => {}); throw e }
+      total += buf.length - before
+      if (total > maxBytes) await trimExcess()
+      return true
+    },
+    async clear() {
+      await start()
+      for (const x of await list()) await fsp.unlink(x.f).catch(() => {})
+      total = 0
+    },
+    stats: () => ({ bytes: total, maxBytes, dir })
+  }
+}
+
+module.exports = { createMemoryCache, createDiskCache, MB }

package/packages/media/erros.js

@@ -0,0 +1,45 @@
+// @morpho/media — erros com código estável (quem usa decide a mensagem para o usuário).
+//
+//   MIDIA_GRANDE        passou do limite de tamanho (antes de baixar, pelo tamanho declarado, ou durante, pelo que chegou)
+//   MIDIA_EXPIRADA      o link do WhatsApp venceu e não deu para recuperar (celular offline, mensagem apagada...)
+//   MIDIA_TIMEOUT       demorou demais (depois das tentativas)
+//   MIDIA_REDE          falha de rede/servidor mesmo depois das tentativas
+//   MIDIA_INVALIDA      mensagem sem chave/endereço, ou conteúdo que não decifra (não adianta tentar de novo)
+//   MIDIA_INDISPONIVEL  qualquer outro erro (a causa original fica em .cause)
+class MediaError extends Error {
+  constructor(code, message, { cause, status } = {}) {
+    super(message)
+    this.name = "MediaError"
+    this.code = code
+    if (status) this.status = status
+    if (cause) this.cause = cause
+  }
+}
+
+const NETWORK_CODES = new Set(["ECONNRESET", "ECONNREFUSED", "ETIMEDOUT", "EAI_AGAIN", "ENOTFOUND", "EPIPE", "ENETUNREACH", "EHOSTUNREACH",
+  "UND_ERR_SOCKET", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT", "ERR_STREAM_PREMATURE_CLOSE"])
+
+// o Baileys lança Boom (output.statusCode); fetch/undici às vezes põe em status; erro de rede cru não tem nenhum
+function statusDe(e) {
+  const n = e?.output?.statusCode ?? e?.statusCode ?? e?.status ?? e?.data?.statusCode ?? e?.data?.status ?? null
+  return Number.isInteger(n) ? n : null
+}
+
+// O que fazer com o erro de UMA tentativa:
+//   "expirada"    -> pedir ao celular para reenviar a mídia (403/404/410: link vencido ou assinatura expirada)
+//   "transitoria" -> tentar de novo depois de uma espera (rede, 429, 5xx, timeout)
+//   "invalida"    -> desistir (não muda de resultado se repetir)
+//   "outro"       -> desconhecido: desiste, sem inventar causa
+function classify(e) {
+  if (e instanceof MediaError) return e.code === "MEDIA_TIMEOUT" ? "transient" : e.code === "MEDIA_INVALID" ? "invalid" : "other"
+  const s = statusDe(e)
+  if (s === 403 || s === 404 || s === 410) return "expired"
+  if (s === 429 || (s !== null && s >= 500)) return "transient"
+  if (s === 400 || s === 401) return "invalid"
+  const msg = String(e?.message || "")
+  if (NETWORK_CODES.has(e?.code) || NETWORK_CODES.has(e?.cause?.code) || /fetch failed|terminated|socket hang up|network|timed? ?out/i.test(msg)) return "transient"
+  if (/bad decrypt|unable to authenticate|unsupported state|invalid (mac|key)|no valid media url|mediakey/i.test(msg)) return "invalid"
+  return "other"
+}
+
+module.exports = { MediaError, classify, statusDe }

package/packages/media/find.js

@@ -0,0 +1,51 @@
+// @morpho/media — find the media inside a WhatsApp message.
+//
+// The unwrapping/typing logic lives in @morpho/message (one source of truth). This file only adds what the downloader
+// needs on top of it: a content-based cache key and the { key, message } pair Baileys wants to ask the phone to re-send
+// media whose CDN link expired.
+const { parse, findMedia } = require("../message")
+
+// bytes from Baileys (Buffer/Uint8Array) or text -> base64; null for anything else
+function b64(x) {
+  if (!x) return null
+  if (typeof x === "string") return x
+  if (x instanceof Uint8Array) return Buffer.from(x).toString("base64")
+  return null
+}
+
+// Identity of the CONTENT, used as cache key. The hash of the decrypted file (fileSha256) is the best one: the same
+// sticker re-sent by different people has the same hash. Without it, other identifiers of the same media are used.
+function cacheKeyOf(node, type) {
+  const id = b64(node?.fileSha256) || b64(node?.fileEncSha256) || b64(node?.mediaKey) || (typeof node?.directPath === "string" ? node.directPath : null)
+  return id ? `${type}:${id}` : null
+}
+
+// The message in the shape Baileys needs to request a re-send ({ key, message }):
+//  - media from the message itself: the message itself;
+//  - media from a reply: builds the quoted message's key (id and author come from the contextInfo).
+//    Whether it was fromMe is only known with the sock (see index.js).
+function resendMessageFor(msg, fromQuoted) {
+  const m = parse(msg)
+  if (!fromQuoted) return m.key?.id && m.chat && msg?.message ? msg : null
+  const ci = m.context
+  if (!ci?.stanzaId || !ci.quotedMessage) return null
+  return {
+    key: { remoteJid: ci.remoteJid || m.chat, id: ci.stanzaId, participant: ci.participant || undefined },
+    message: ci.quotedMessage
+  }
+}
+
+// A document only counts when it is really an audio/video/image
+const realMedia = a => a.type !== "document" || a.family !== "other"
+
+// types:  list of "image" | "video" | "audio" | "sticker" | "document" (default: all)
+// quoted: "prefer" (default: the quoted message's media, else the message's own) | "only" | "never"
+// returns the @morpho/message media object (type, kind, mimetype, seconds, size, ptt, animated, fileName, viewOnce, node, fromQuoted...)
+// plus { msg, resendMessage, cacheKey }, or null.
+function find(msg, { types, quoted = "prefer" } = {}) {
+  const media = findMedia(msg, { types, quoted, accept: realMedia })
+  if (!media) return null
+  return { ...media, msg, resendMessage: resendMessageFor(msg, media.fromQuoted), cacheKey: cacheKeyOf(media.node, media.type) }
+}
+
+module.exports = { find, cacheKeyOf, resendMessageFor }

package/packages/media/index.js

@@ -0,0 +1,261 @@
+// @morpho/media — download de mídia do WhatsApp que não desiste.
+//
+// O que o Baileys sozinho não resolve (e o Morvyn ia refazendo em cada comando):
+//   1. ACHAR a mídia: a da mensagem marcada tem prioridade, senão a da própria; entende visualização única,
+//      mensagem temporária, legenda de documento...
+//   2. LINK EXPIRADO: o endereço da mídia no CDN do WhatsApp vence (403/404/410). Em vez de falhar, pede ao celular
+//      que reenvie (sock.updateMediaMessage), com limite de tempo, UMA vez, e baixa de novo.
+//   3. LIMITES: tamanho (pelo declarado ANTES de baixar e pelo que realmente chega), tempo e quantidade simultânea.
+//   4. RETRY só onde faz sentido: rede, 429 e 5xx tentam de novo com espera; link vencido pede reenvio; chave/decifra
+//      inválida desiste na hora.
+//   5. CACHE: memória (LRU por bytes) e disco (opcional, sobrevive a reinício). A mesma figurinha usada por todo o
+//      grupo é baixada uma vez só; pedidos iguais ao mesmo tempo viram UMA consulta.
+//
+//   const { criarMidia } = require("@morpho/media")
+//   const midia = criarMidia({ disco: { dir: "./cache/media" } })
+//   midia.vincular(msg, sock)                       // opcional: diz de qual sock é a mensagem (para o pedido de reenvio)
+//   const r = await midia.baixar(msg, { tipos: ["image", "video"] })   // null se não há mídia
+//   r.buffer, r.tipo, r.mimetype, r.origem          // origem: "memoria" | "disco" | "rede" | "reenvio"
+//
+// Sem dependência do Baileys no código: o downloader padrão o carrega só quando precisa, e dá para trocar
+// (opção `download`), o que também permite testar sem WhatsApp.
+const { findMedia } = require("../message")
+const { find: findBase } = require("./find")
+const { MediaError, classify, statusDe } = require("./erros")
+const { createMemoryCache, createDiskCache, MB } = require("./cache")
+
+const DEFAULT_MAX = 50 * MB
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+const part = j => String(j || "").split("@")[0].split(":")[0]
+const isMine = (sock, participantJid) => !!participantJid && [sock?.user?.id, sock?.user?.lid].filter(Boolean).map(part).includes(part(participantJid))
+
+const tooLarge = n => new MediaError("MEDIA_TOO_LARGE", n ? `Mídia grande demais (${Math.round(n / MB)} MB)` : "Mídia grande demais")
+
+function withTimeout(promise, ms, onTimeout) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => { try { onTimeout?.() } catch { /* já fechado */ } reject(new MediaError("MEDIA_TIMEOUT", `Passou de ${ms}ms`)) }, ms)
+    promise.then(v => { clearTimeout(t); resolve(v) }, e => { clearTimeout(t); reject(e) })
+  })
+}
+
+function createSemaphore(n) {
+  let free = n
+  const queue = []
+  return {
+    async acquire() { if (free > 0) { free--; return } await new Promise(r => queue.push(r)) },
+    release() { const next = queue.shift(); if (next) next(); else free++ },
+    backoff: () => queue.length
+  }
+}
+
+const baileysDownloader = () => (node, type) => require("../core/baileys").loadBaileys().downloadContentFromMessage(node, type)
+
+// converte o erro cru da última tentativa no erro com código estável
+function convert(e, cls) {
+  if (e instanceof MediaError) return e
+  const status = statusDe(e) || undefined
+  if (cls === "transient") return new MediaError("MEDIA_NETWORK", `Falha de rede ao baixar a mídia: ${e?.message || e}`, { cause: e, status })
+  if (cls === "invalid") return new MediaError("MEDIA_INVALID", `Mídia inválida: ${e?.message || e}`, { cause: e, status })
+  return new MediaError("MEDIA_UNAVAILABLE", `Não consegui baixar a mídia: ${e?.message || e}`, { cause: e, status })
+}
+
+// opções:
+//   download      (no, tipo) => stream | Buffer       padrão: downloadContentFromMessage do Baileys
+//   max           bytes aceitos por download           padrão 50 MB (cada chamada pode passar o seu)
+//   timeoutMs     limite de UMA tentativa              padrão 45 s
+//   tentativas    retries em erro de rede/429/5xx      padrão 2 (3 tentativas no total)
+//   espera        (n) => ms antes do retry n           padrão 400ms, 1,2s, 3,6s...
+//   reuploadTimeoutMs  limite do pedido de reenvio ao celular   padrão 30 s
+//   concorrencia  downloads ao mesmo tempo             padrão 4 (o resto espera na fila)
+//   cache         false | { maxBytes, maxEntrada, ttlMs }   memória; padrão 64 MB, entrada até 8 MB, 10 min
+//   cacheUmaVez   guardar também mídia de "visualização única"?   padrão false (privacidade: nunca vai para memória nem disco)
+//   disco         { dir, maxBytes, maxEntrada, ttlMs }      cache em disco (desligado se não passar)
+//   copiar        entrega cópia do que está no cache (padrão true: quem altera o Buffer não estraga o cache)
+//   log           (evento, dados) => void              "reenvio", "retry", "cache-disco-erro"
+function createMedia({ downloader, max = DEFAULT_MAX, timeoutMs = 45e3, retries = 2, backoff = n => 400 * 3 ** n, reuploadTimeoutMs = 30e3,
+  concurrency = 4, cache, disk, cacheViewOnce = false, copy = true, log } = {}) {
+
+  const fetchBytes = downloader || baileysDownloader()
+  const memory = cache === false ? null : createMemoryCache(cache && typeof cache === "object" ? cache : {})
+  const onDisk = disk ? createDiskCache(disk) : null
+  const semaphore = createSemaphore(Math.max(1, concurrency))
+  const bindings = new WeakMap()   // objeto da mensagem -> sock que a recebeu
+  const pending = new Map()         // cacheKey -> Promise (download em andamento: pedidos iguais esperam o mesmo)
+  const resendsInFlight = new Map() // id da mensagem -> Promise (um pedido de reenvio por mensagem)
+  const st = { memoryHits: 0, diskHits: 0, cacheMisses: 0, downloads: 0, retries: 0, resends: 0, resendsOk: 0, errors: 0, bytesDownloaded: 0 }
+  const notify = (event, data) => { try { log?.(event, data) } catch { /* log não pode derrubar o download */ } }
+
+  // ---------- cache ----------
+  async function readCache(key) {
+    const m = memory?.get(key)
+    if (m) { st.memoryHits++; return { buffer: m, source: "memory" } }
+    if (onDisk) {
+      try {
+        const d = await onDisk.get(key)
+        if (d) { memory?.set(key, d); st.diskHits++; return { buffer: d, source: "disk" } }
+      } catch (e) { notify("disk-cache-error", e) }
+    }
+    st.cacheMisses++
+    return null
+  }
+  async function save(key, buf) {
+    memory?.set(key, buf)
+    if (onDisk) { try { await onDisk.set(key, buf) } catch (e) { notify("disk-cache-error", e) } }
+  }
+
+  // ---------- UMA tentativa de download (com fila, limite de tamanho e de tempo) ----------
+  async function attemptOnce(node, type, maxSize, limitMs) {
+    await semaphore.acquire()
+    let stream
+    try {
+      const read = (async () => {
+        stream = await fetchBytes(node, type)
+        if (Buffer.isBuffer(stream) || stream instanceof Uint8Array) {
+          const b = Buffer.from(stream)
+          if (b.length > maxSize) throw tooLarge(b.length)
+          return b
+        }
+        const chunks = []
+        let total = 0
+        for await (const p of stream) {
+          total += p.length
+          if (total > maxSize) throw tooLarge(total) // sair do laço fecha o stream: para de baixar na hora
+          chunks.push(p)
+        }
+        return Buffer.concat(chunks)
+      })()
+      read.catch(() => {}) // se o tempo estourar primeiro, o erro tardio daqui não pode virar rejeição sem dono
+      return await withTimeout(read, limitMs, () => { try { stream?.destroy?.() } catch { /* já fechado */ } })
+    } finally { semaphore.release() }
+  }
+
+  // ---------- link expirado: pede ao celular que reenvie a mídia ----------
+  // devolve o nó da mídia já com o endereço novo
+  function requestResend(found, sock) {
+    if (typeof sock?.updateMediaMessage !== "function")
+      throw new MediaError("MEDIA_EXPIRED", "O link da mídia expirou e não há como pedir o reenvio (sem o sock).")
+    const base = found.resendMessage
+    if (!base) throw new MediaError("MEDIA_EXPIRED", "O link da mídia expirou e a mensagem não traz identificador para pedir o reenvio.")
+
+    const id = `${base.key?.remoteJid}|${base.key?.id}`
+    if (resendsInFlight.has(id)) return resendsInFlight.get(id)
+
+    const p = (async () => {
+      st.resends++
+      // mídia de uma resposta: o Baileys precisa saber se a citada era do próprio bot
+      const msg = found.fromQuoted ? { ...base, key: { ...base.key, fromMe: isMine(sock, base.key?.participant) } } : base
+      let r
+      try { r = await withTimeout(Promise.resolve(sock.updateMediaMessage(msg)), reuploadTimeoutMs) }
+      catch (e) { throw new MediaError("MEDIA_EXPIRED", "O link da mídia expirou e o celular não reenviou a tempo (offline, ou a mensagem foi apagada).", { cause: e }) }
+      // o Baileys atualiza a mensagem no lugar; se devolveu outra, lê o endereço novo dela
+      const m = r?.message ? r : msg
+      st.resendsOk++
+      return findMedia({ key: m.key, message: m.message }, { quoted: "never" })?.node || found.node
+    })()
+    resendsInFlight.set(id, p)
+    const clear = () => resendsInFlight.delete(id)
+    p.then(clear, clear)
+    return p
+  }
+
+  // ---------- baixar de verdade: retry, reenvio, tudo ----------
+  async function fetchWithRetry(found, { sock, maxSize, limitMs, reupload }) {
+    let node = found.node, resent = false, tries = 0
+    for (;;) {
+      try {
+        st.downloads++
+        const buffer = await attemptOnce(node, found.type, maxSize, limitMs)
+        st.bytesDownloaded += buffer.length
+        return { buffer, source: resent ? "resend" : "network" }
+      } catch (e) {
+        if (e?.code === "MEDIA_TOO_LARGE") throw e
+        const cls = classify(e)
+        if (cls === "expired") {
+          if (resent || !reupload) throw new MediaError("MEDIA_EXPIRED", "O link da mídia expirou no WhatsApp.", { cause: e, status: statusDe(e) || undefined })
+          resent = true
+          notify("resend", { type: found.type, status: statusDe(e) })
+          node = await requestResend(found, sock)
+          continue
+        }
+        if (cls === "transient" && tries < retries) {
+          notify("retry", { attempt: tries + 1, error: e?.message })
+          st.retries++
+          await sleep(backoff(tries++))
+          continue
+        }
+        throw convert(e, cls)
+      }
+    }
+  }
+
+  // ---------- API ----------
+  const findWithSock = (msg, o) => {
+    const a = findBase(msg, o)
+    if (a) a.sock = (msg && typeof msg === "object" && bindings.get(msg)) || null
+    return a
+  }
+
+  // opções: { sock, max, timeoutMs, cache (false = ignora o cache), reupload (false = não pede reenvio) }
+  // devolve { buffer, tipo, mimetype, tamanho, citada, nomeArquivo, segundos, ptt, animado, origem } ou null (achado vazio)
+  async function downloadFound(found, opts = {}) {
+    if (!found) return null
+    const maxSize = opts.max ?? max
+    if (found.size > maxSize) throw tooLarge(found.size)
+    const sock = opts.sock ?? found.sock ?? (found.msg && typeof found.msg === "object" ? bindings.get(found.msg) : null) ?? null
+    const key = opts.cache === false || (found.viewOnce && !cacheViewOnce) ? null : found.cacheKey
+
+    try {
+      let r = key ? await readCache(key) : null
+      if (!r) {
+        const run = () => fetchWithRetry(found, { sock, maxSize, limitMs: opts.timeoutMs ?? timeoutMs, reupload: opts.reupload !== false })
+        if (key) {
+          let p = pending.get(key)
+          if (!p) {
+            p = run().then(async x => { await save(key, x.buffer); return x })
+            pending.set(key, p)
+            const clear = () => { if (pending.get(key) === p) pending.delete(key) }
+            p.then(clear, clear)
+          }
+          r = await p
+        } else r = await run()
+      }
+      if (r.buffer.length > maxSize) throw tooLarge(r.buffer.length) // o cache/pedido de outro tinha limite maior que o deste chamador
+      const buffer = key && copy ? Buffer.from(r.buffer) : r.buffer
+      return {
+        buffer, type: found.type, mimetype: found.mimetype, size: buffer.length, fromQuoted: found.fromQuoted,
+        fileName: found.fileName, seconds: found.seconds, ptt: found.ptt, animated: found.animated, source: r.source
+      }
+    } catch (e) { st.errors++; throw e }
+  }
+
+  // aceita a mensagem (acha a mídia sozinho) ou um achado de achar(). Opções de achar() (tipos, citada) valem junto.
+  function download(target, opts = {}) {
+    const found = target && target.node && target.type ? target : findWithSock(target, opts)
+    return downloadFound(found, opts)
+  }
+
+  // Guarda no cache uma mídia que ACABOU de chegar, antes de o link ter chance de vencer. Nunca lança (devolve true/false).
+  // Não liga sozinho: baixar tudo que chega pesa. Use para o que vale a pena (ex.: figurinhas e imagens pequenas de grupo).
+  async function prefetch(msg, { types = ["sticker", "image"], max: maxSize = 2 * MB, ...rest } = {}) {
+    try {
+      const a = findWithSock(msg, { types, quoted: "never" })
+      if (!a?.cacheKey || a.viewOnce || a.size > maxSize) return false
+      await downloadFound(a, { ...rest, max: maxSize, reupload: false })
+      return true
+    } catch { return false }
+  }
+
+  return {
+    find: findWithSock,
+    download,
+    downloadFound,
+    prefetch,
+    // diz de qual sock é esta mensagem: o pedido de reenvio de mídia expirada precisa dele, e quem chama baixar(msg)
+    // de dentro de um comando nem sempre tem o sock à mão
+    bind(msg, sock) { if (msg && typeof msg === "object") bindings.set(msg, sock) },
+    stats: () => ({ ...st, inFlight: pending.size, queued: semaphore.backoff(), memory: memory?.stats() ?? null, disk: onDisk?.stats() ?? null }),
+    async clearCache() { memory?.clear(); await onDisk?.clear() }
+  }
+}
+
+module.exports = { createMedia, MediaError, classify, find: findBase, DEFAULT_MAX, createMemoryCache, createDiskCache }

package/packages/media/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@morpho/media",
+  "version": "0.2.0",
+  "description": "WhatsApp media download that does not give up: finds the media (reply or own), downloads with size limit, timeout and retry, recovers expired-link media by asking the phone to re-send it, and caches it (memory + optional disk).",
+  "main": "index.js",
+  "dependencies": { "@morpho/message": "file:../message" },
+  "license": "MIT"
+}

package/packages/message/README.md

@@ -0,0 +1,53 @@
+# morpho-socket/message
+
+One function that turns a raw Baileys message into a **simple object that always has the same shape**.
+
+The raw message hides the real content under wrappers (`ephemeralMessage`, `viewOnceMessageV2`, `editedMessage`, `documentWithCaptionMessage`…), and the text lives in a different place for every type (`conversation`, `extendedTextMessage.text`, `imageMessage.caption`…). `parse()` unwraps all of it once, in one place.
+
+```js
+const { parse } = require("morpho-socket/message")
+
+sock.ev.on("messages.upsert", ({ messages }) => {
+  const m = parse(messages[0])
+
+  m.type      // "text" | "image" | "video" | "gif" | "videoNote" | "audio" | "voice" | "sticker" | "document" | ...
+  m.text      // text or caption ("" if none)
+  m.mentions  // mentioned JIDs — in ANY message type, not only text
+  m.media     // { type, mimetype, seconds, size, ptt, animated, viewOnce, fileName, ... } or null
+  m.quoted    // the replied-to message, parsed the same way (or null)
+})
+```
+
+`parse()` **never throws**: a null message, one that could not be decrypted, or an unknown type becomes `type: "empty"` / `"unknown"`. Parsing the same message object twice returns the same result.
+
+## The parsed message
+
+| Group | Fields |
+|---|---|
+| where / who (raw JIDs — [`jid`](../jid) resolves LID → number) | `id` `chat` `sender` `senderAlt` `fromMe` `isGroup` `isStatus` `isNewsletter` `pushName` `timestamp` `key` |
+| what | `type` `kind` (the original Baileys key, e.g. `"imageMessage"`) `text` `media` `selection` `reaction` `pollKey` |
+| details | `mentions` `forwarded` `viewOnce` `edited` `editTarget` `revoked` `ephemeral` `expiration` `stub` `protocol` |
+| raw | `context` (the raw `contextInfo`) · `node` (the raw content) |
+| helper | `m.is("image", "video")` · `m.quoted` (lazy) |
+
+**Types:** `text` `image` `video` `gif` `videoNote` `audio` `voice` `sticker` `document` `contact` `location` `poll` `pollVote` `reaction` `interactive` `reply` `invite` `event` `album` `other` · plus `system` `revoke` `empty` `unknown`.
+
+- A tap on a button or list row has `type: "reply"` and `m.selection = { id, text }`.
+- An edited message arrives as its **new** content with `edited: true`; a deleted one is `type: "revoke"`.
+- `unknown` means a Baileys key Morpho does not know yet — check `m.kind`.
+
+## Finding media
+
+```js
+const { findMedia } = require("morpho-socket/message")
+
+findMedia(msg, { types: ["image", "video"], quoted: "prefer" })   // → media object (+ fromQuoted) or null
+```
+
+`quoted`: `"prefer"` (default — the replied-to message's media wins, so replying to a sticker with a command works), `"only"`, or `"never"`. `families` also matches documents that are really images/video/audio; `accept(media)` is an extra filter.
+
+## Other exports
+
+`unwrap(message)` · `textOf(msg)` · `toNumber(x)` (numbers, bigint, protobuf `Long` → number) · `WRAPPERS` · `MEDIA_TYPES`
+
+Zero dependencies.