morpho-socket 0.0.0-stage → 0.3.0

package/packages/pool/index.js

@@ -0,0 +1,369 @@
+// @morpho/pool — camada 2 do Morpho.
+//
+// A camada 1 (@morpho/core + @morpho/store-*) resolve ONDE a sessão fica guardada.
+// Esta camada resolve COMO GERIR várias sessões no mesmo processo: conectar, pedir código de
+// pareamento quando não há sessão salva, reconectar sozinho quando a conexão cai (com backoff,
+// pra não martelar o WhatsApp), parar, resetar. É a parte genérica do sessoes.js de um bot
+// multi-cliente — SEM nenhuma regra de negócio (plano, limite de grupo, quem é dono) misturada.
+// Quem usa pluga a própria regra por fora, pelos eventos.
+//
+//   const pool = new MorphoPool({ store, initCreds: require("@whiskeysockets/baileys").initAuthCreds })
+//   pool.on("pairing-code", (sessionId, codigo) => console.log(sessionId, "->", codigo))
+//   pool.on("connect",     (sessionId, sock)   => { ...sua regra de negócio... })
+//   pool.on("disconnect",  (sessionId, info)   => { ... })
+//   pool.on("logged-out",  (sessionId)         => { ... }) // terminal: não tenta mais sozinho
+//   await pool.start("cliente-a", { numero: "5511999999999" })
+//
+// Mais:
+//   pool.on("socket", (sessionId, sock, { ouvir }) => ouvir("messages.upsert", ...))
+//       socket novo a CADA (re)conexão. `ouvir` é o sock.ev.on com duas proteções: ignora evento de socket antigo (já
+//       trocado por uma reconexão) e erro dentro do ouvinte vira evento "error" em vez de derrubar o processo.
+//   pool.on("replaced" | "forbidden" | "gave-up" | "stopped", ...)   quedas que NÃO reconectam (ver POLITICA_PADRAO)
+//   await pool.startAll(["a", "b", { sessionId: "c", numero: "55..." }], { intervaloMs: 1500 })
+//   pool.info("a") -> { status, tentativas, pareada, motivoParada }
+
+const EventEmitter = require("events")
+const { useMorphoAuthState } = require("../core")
+
+const STATUS = { CONNECTING: "connecting", OPEN: "open", RECONNECTING: "reconnecting", STOPPED: "stopped" }
+
+const withTimeout = (promise, ms) => new Promise((resolve, reject) => {
+  const t = setTimeout(() => reject(new Error(`timeout de ${ms}ms`)), ms)
+  promise.then(v => { clearTimeout(t); resolve(v) }, e => { clearTimeout(t); reject(e) })
+})
+const VERSION_TTL_MS = 60 * 60 * 1000
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+// Por que o WhatsApp fechou a conexão (DisconnectReason do Baileys, sem acoplar ao enum aqui).
+const CLOSE_REASONS = {
+  401: "logged-out",       // saiu do aparelho / sessão revogada
+  403: "forbidden",        // número restringido ou banido
+  408: "timeout",
+  411: "multidevice",
+  428: "connection-closed",
+  440: "replaced",     // OUTRA instância abriu a mesma sessão (reconectar só inicia uma briga entre as duas)
+  500: "bad-session",
+  503: "unavailable",
+  515: "restart-required"        // normal logo depois de parear: o WhatsApp pede um socket novo
+}
+// O que fazer em cada código. "reconectar" = com backoff (o padrão para tudo que não está aqui);
+// "imediato" = já, sem gastar o backoff (no máx. MAX_IMEDIATOS seguidas); "parar" = terminal.
+const DEFAULT_POLICY = { 401: "stop", 403: "stop", 440: "stop", 515: "immediate" }
+const TERMINAL_EVENT = { 401: "logged-out", 403: "forbidden", 440: "replaced" }
+const MAX_IMMEDIATE = 3
+
+class MorphoPool extends EventEmitter {
+  // maxTentativasSemParear: número que NUNCA foi pareado (ninguém digitou o código) para de tentar depois de N quedas
+  //   seguidas e emite "gave-up" (null = tenta para sempre, o comportamento antigo).
+  // politica: { [codigo]: "reconectar" | "imediato" | "parar" } sobre a POLITICA_PADRAO. O 401 sempre para.
+  constructor({ store, initCreds, makeSocket, socketConfig, backoff, versionTimeoutMs = 5000, skipNetworkVersion = false, maxAttemptsWithoutPairing = null, policy = {} } = {}) {
+    super()
+    if (!store || typeof store.readCreds !== "function")
+      throw new Error("MorphoPool: 'store' é obrigatório (um MorphoAuthStore, ver @morpho/core).")
+    if (typeof initCreds !== "function")
+      throw new Error("MorphoPool: 'initCreds' é obrigatório (ex.: require('@whiskeysockets/baileys').initAuthCreds).")
+
+    this.store = store
+    this.initCreds = initCreds
+    this.maxAttemptsWithoutPairing = maxAttemptsWithoutPairing
+    this.policy = { ...DEFAULT_POLICY, ...policy, 401: "stop" }
+    // socketConfig(sessionId, state) -> extra makeWASocket options (getMessage, cachedGroupMetadata, browser...), merged into the default factory
+    this.socketConfig = socketConfig
+    this.makeSocket = makeSocket || this._defaultFactory.bind(this)
+    // backoff(tentativa) -> ms de espera. Padrão: exponencial, 2s/4s/8s/16s/32s, teto de 60s.
+    this.backoff = backoff || (attempt => Math.min(60000, 2000 * 2 ** attempt))
+    this._sessions = new Map() // sessionId -> { sock, status, tentativas, timer, opts }
+    this.versionTimeoutMs = versionTimeoutMs
+    // DIAGNÓSTICO: desde fev/2026 o WhatsApp vem rejeitando pareamento com versão de protocolo
+    // desatualizada, e fetchLatestBaileysVersion() às vezes devolve uma versão que já não serve
+    // mais, sem erro nenhum (não é falha de rede, é resposta "válida" porém velha). Com isso em
+    // true, nem tenta buscar: usa a versão que já vem empacotada dentro do próprio Baileys.
+    this.skipNetworkVersion = skipNetworkVersion
+    this._version = null       // última versão do protocolo obtida com sucesso (cache, ver _versaoBaileys)
+    this._versionAt = 0
+  }
+
+  // --- fábrica de socket padrão, usando o Baileys de verdade. Quem testa (ou quem quiser outra
+  // configuração de makeWASocket) pode passar um "makeSocket" próprio no construtor.
+  async _defaultFactory({ sessionId, state }) {
+    const baileys = require("../core/baileys").loadBaileys()
+    const { fetchLatestBaileysVersion, Browsers } = baileys
+    // Baileys 6 exporta makeWASocket nomeado; o 7 (ESM) pode entregá-lo só como default
+    const makeWASocket = baileys.makeWASocket ?? baileys.default?.makeWASocket ?? baileys.default
+    let version
+    if (this.skipNetworkVersion) console.warn("[morpho/pool] semVersaoDaRede ligado: usando a versão de protocolo empacotada no Baileys, sem consultar a rede.")
+    else version = await this._baileysVersion(fetchLatestBaileysVersion)
+
+    // "Nome (SO)" — vários relatos recentes apontam Browsers.ubuntu(...) como instável
+    // especificamente no fluxo de CÓDIGO DE PAREAMENTO (QR é mais tolerante a isso)
+    const config = { auth: state, logger: require("../core/baileys").silentLogger(), printQRInTerminal: false, browser: Browsers.macOS("Chrome") }
+    Object.assign(config, await this.socketConfig?.(sessionId, state))
+    if (version) config.version = version // sem versão: o Baileys usa a embutida
+    return makeWASocket(config)
+  }
+
+  // A versão do protocolo vem de uma consulta de rede, e a reconexão acontece justamente quando a rede pode
+  // estar fora: a consulta não pode travar (timeout) e não precisa repetir a cada tentativa (cache de 1h; se a
+  // rede cair depois do cache vencer, vale a última versão boa). Sem versão nenhuma, o Baileys usa a embutida
+  // (que pode estar desatualizada em relação ao que o WhatsApp aceita hoje), então avisamos em vez de seguir calado.
+  async _baileysVersion(fetchLatestBaileysVersion) {
+    if (this._version && Date.now() - this._versionAt < VERSION_TTL_MS) return this._version
+    try {
+      const r = await withTimeout(Promise.resolve(fetchLatestBaileysVersion()), this.versionTimeoutMs)
+      if (r?.version && r.isLatest !== false) { this._version = r.version; this._versionAt = Date.now(); return r.version }
+      // sem rede o Baileys não lança erro: devolve a versão embutida com isLatest:false
+      this._warnVersion(r?.error?.message || "o servidor de versões não respondeu")
+      return this._version || r?.version
+    } catch (e) {
+      this._warnVersion(e.message)
+      return this._version || undefined
+    }
+  }
+
+  _warnVersion(reason) {
+    console.warn(
+      `[morpho/pool] não consegui buscar a versão mais recente do protocolo (sem internet aqui?); usando ${this._version ? "a última versão obtida" : "a versão empacotada no Baileys, que pode estar desatualizada"}:`,
+      reason
+    )
+  }
+
+  // --- API pública ---------------------------------------------------------------------------
+
+  // Conecta (ou reaproveita, se já estiver rodando). opts.numero só é usado se ainda não houver
+  // sessão salva (pareamento). Devolve uma promise que resolve quando a conexão abre PELA PRIMEIRA
+  // VEZ nesta chamada — reconexões automáticas depois disso são só eventos, não bloqueiam ninguém.
+  async start(sessionId, opts = {}) {
+    const current = this._sessions.get(sessionId)
+    if (current && current.status !== STATUS.STOPPED) return current.sock
+
+    const entry = { sock: null, status: STATUS.CONNECTING, attempts: 0, immediates: 0, timer: null, opts, state: null, stopReason: null }
+    this._sessions.set(sessionId, entry)
+
+    return new Promise((resolve, reject) => {
+      entry._resolveFirstConnection = resolve
+      entry._rejectFirstConnection = reject
+      this._connect(sessionId).catch(e => this._fatalFailure(sessionId, e))
+    })
+  }
+
+  // Sobe várias sessões com um intervalo entre elas (todas ao mesmo tempo no boot é o que o WhatsApp mais estranha).
+  // Não espera abrir: uma sessão nova pode ficar minutos esperando alguém digitar o código. Quem avisa é o evento
+  // "connect"; falha vira evento "error". Itens: "id" ou { sessionId, numero } ou { sessionId, opts }.
+  async startAll(items, { intervalMs = 1500 } = {}) {
+    const list = [...items]
+    const started = []
+    for (let i = 0; i < list.length; i++) {
+      const item = list[i]
+      const sessionId = typeof item === "string" ? item : item.sessionId
+      const opts = typeof item === "string" ? {} : (item.opts || (item.phoneNumber ? { phoneNumber: item.phoneNumber } : {}))
+      this.start(sessionId, opts).catch(() => { /* já emitido como "error" */ })
+      started.push(sessionId)
+      if (i < list.length - 1 && intervalMs > 0) await sleep(intervalMs)
+    }
+    return started
+  }
+
+  // Retrato de uma sessão (para painel).
+  info(sessionId) {
+    const e = this._sessions.get(sessionId)
+    if (!e) return { sessionId, status: STATUS.STOPPED, attempts: 0, paired: false, stopReason: null }
+    return { sessionId, status: e.status, attempts: e.attempts, paired: this._isPaired(e), stopReason: e.stopReason || null }
+  }
+
+  // Encerra a sessão sem apagar as credenciais: dá pra chamar start() de novo depois, sem parear.
+  stop(sessionId) {
+    const entry = this._sessions.get(sessionId)
+    if (!entry) return
+    entry.status = STATUS.STOPPED
+    if (entry.timer) clearTimeout(entry.timer)
+    entry.timer = null
+    try { entry.sock?.end?.(new Error("parado via MorphoPool.stop()")) } catch { /* já pode estar fechado */ }
+    entry.sock = null
+  }
+
+  // Encerra E apaga a sessão salva: a próxima start() vai pedir pareamento de novo.
+  async reset(sessionId) {
+    this.stop(sessionId)
+    this._sessions.delete(sessionId)
+    await this.store.deleteSession(sessionId)
+  }
+
+  get(sessionId) { return this._sessions.get(sessionId)?.sock ?? null }
+
+  status(sessionId) { return this._sessions.get(sessionId)?.status ?? STATUS.STOPPED }
+
+  list() { return [...this._sessions.entries()].map(([sessionId, e]) => ({ sessionId, status: e.status })) }
+
+  // --- interno ---------------------------------------------------------------------------------
+
+  // `reconexao` = foi o timer do backoff que chamou (e não o start()). A diferença importa no erro: falhar na
+  // 1ª criação rejeita o start() (quem chamou precisa saber); falhar numa reconexão não pode matar a sessão.
+  async _connect(sessionId, isReconnect = false) {
+    const entry = this._sessions.get(sessionId)
+    if (!entry || entry.status === STATUS.STOPPED) return // start() seguido de stop() antes de terminar
+
+    // stop()/reset()/novo start() podem acontecer enquanto esperamos um await abaixo: sempre rechecar depois
+    const alive = () => this._sessions.get(sessionId) === entry && entry.status !== STATUS.STOPPED
+
+    let state, saveCreds
+    try {
+      await this._discardIncompletePairing(sessionId)
+      const auth = await useMorphoAuthState(this.store, sessionId, { initCreds: this.initCreds })
+      state = auth.state; saveCreds = auth.saveCreds
+    } catch (e) { return this._creationFailure(sessionId, entry, e, isReconnect) }
+    if (!alive()) return
+
+    let sock
+    try { sock = await this.makeSocket({ sessionId, state, saveCreds }) }
+    catch (e) { return this._creationFailure(sessionId, entry, e, isReconnect) }
+    if (!alive()) { // pararam durante a criação: este socket nasceu sem dono, não pode ficar conectado
+      try { sock?.end?.(new Error("sessão parada durante a criação do socket")) } catch { /* já fechado */ }
+      return
+    }
+
+    entry.sock = sock
+    entry.state = state
+    this._announceSocket(sessionId, entry, sock)
+    // falha ao salvar não pode virar rejeição não tratada (derruba o Node): vira evento "error"
+    sock.ev.on("creds.update", () => {
+      try { Promise.resolve(saveCreds()).catch(e => this._emitError(sessionId, e)) }
+      catch (e) { this._emitError(sessionId, e) }
+    })
+    // o ouvinte de conexão precisa existir ANTES de qualquer await abaixo: se a conexão cair enquanto o código
+    // de pareamento é pedido, esse evento não pode se perder (a sessão ficaria sem reconexão)
+    // O código de pareamento só pode ser pedido DEPOIS que o WhatsApp responde ao handshake, o que ele sinaliza
+    // mandando o evento "qr". Pedir logo após makeWASocket() dá "Connection Closed" (o socket ainda nem abriu) E
+    // pior: o requestPairingCode grava creds.me ANTES de enviar; o handshake então vê "me" preenchido, acha que
+    // este device já existe, manda LOGIN em vez de REGISTRO e o servidor responde 401 "Connection Failure".
+    // O Morvyn já faz assim (pedirCodigo dentro do connection.update, quando u.qr chega).
+    let requestedCode = false
+    sock.ev.on("connection.update", update => {
+      this._onConnectionUpdate(sessionId, sock, update)
+      if (update.qr && !requestedCode && !state.creds.registered && entry.opts.phoneNumber) {
+        requestedCode = true
+        this._requestCode(sessionId, entry, sock, entry.opts.phoneNumber, alive)
+      }
+    })
+  }
+
+  async _requestCode(sessionId, entry, sock, phoneNumber, alive) {
+    try {
+      const code = await sock.requestPairingCode(String(phoneNumber).replace(/\D/g, ""))
+      if (alive() && entry.sock === sock) this.emit("pairing-code", sessionId, code)
+    } catch (e) { this._emitError(sessionId, e) }
+  }
+
+  // Credencial que existe mas nunca completou o pareamento (registered:false e sem "account", que só aparece no
+  // pair-success) é lixo de uma tentativa que falhou: ela já tem creds.me (gravado pelo requestPairingCode), e
+  // reaproveitá-la faz o próximo socket mandar LOGIN de um device que não existe → 401 de novo, pra sempre.
+  // Descartar aqui evita ter que "apagar o sqlite na mão". Sessão pareada de verdade (registered ou account) nunca é tocada.
+  async _discardIncompletePairing(sessionId) {
+    const creds = await this.store.readCreds(sessionId)
+    if (creds && !creds.registered && !creds.account) await this.store.deleteSession(sessionId)
+  }
+
+  _onConnectionUpdate(sessionId, sock, update) {
+    const entry = this._sessions.get(sessionId)
+    // parada, ou evento de um socket antigo (já trocado por uma reconexão): não é da conta da sessão atual
+    if (!entry || entry.status === STATUS.STOPPED || entry.sock !== sock) return
+
+    if (update.connection === "open") {
+      entry.status = STATUS.OPEN
+      entry.attempts = 0 // sucesso zera o backoff
+      entry.immediates = 0
+      this.emit("connect", sessionId, entry.sock)
+      entry._resolveFirstConnection?.(entry.sock)
+      delete entry._resolveFirstConnection
+    }
+
+    if (update.connection === "close") {
+      const code = update.lastDisconnect?.error?.output?.statusCode
+      const message = update.lastDisconnect?.error?.message
+      const loggedOut = code === 401 // DisconnectReason.loggedOut
+      const reason = CLOSE_REASONS[code] || (code ? "unknown" : "dropped")
+      const action = this.policy[code] || "reconnect"
+      entry.sock = null // esse socket morreu: eventos tardios dele caem na checagem acima, e get() não entrega socket morto
+      this.emit("disconnect", sessionId, { code, message, loggedOut, reason, action })
+
+      if (action === "stop") {
+        const label = loggedOut ? `Sessão deslogada durante o pareamento (código ${code}: ${message})` : `Sessão parada pelo WhatsApp (${reason}, código ${code}: ${message})`
+        return this._halt(sessionId, entry, { code, message, reason }, TERMINAL_EVENT[code], new Error(label))
+      }
+      if (action === "immediate" && entry.immediates < MAX_IMMEDIATE) {
+        entry.immediates++
+        return this._scheduleReconnect(sessionId, entry, { immediate: true, reason })
+      }
+      this._scheduleReconnect(sessionId, entry, { reason })
+    }
+  }
+
+  // Parada terminal (logout, substituída, proibida, desistência): não reconecta sozinho. start() de novo recomeça.
+  _halt(sessionId, entry, info, event, error) {
+    entry.status = STATUS.STOPPED
+    entry.stopReason = info.reason
+    if (entry.timer) { clearTimeout(entry.timer); entry.timer = null }
+    if (event) this.emit(event, sessionId, info)
+    this.emit("stopped", sessionId, info)
+    entry._rejectFirstConnection?.(error)
+    delete entry._rejectFirstConnection
+  }
+
+  // Sessão que já completou o pareamento (registered, ou account, que só aparece no pair-success).
+  _isPaired(entry) {
+    const c = entry.state?.creds
+    return !!(c?.registered || c?.account)
+  }
+
+  // Avisa quem quer ligar ouvintes no socket novo. O `ouvir` ignora evento de socket já trocado e não deixa erro de
+  // ouvinte virar rejeição não tratada.
+  _announceSocket(sessionId, entry, sock) {
+    if (this.listenerCount("socket") === 0) return
+    const listen = (event, fn) => sock.ev.on(event, (...args) => {
+      if (entry.sock !== sock || entry.status === STATUS.STOPPED) return
+      try { Promise.resolve(fn(...args)).catch(e => this._emitError(sessionId, e)) }
+      catch (e) { this._emitError(sessionId, e) }
+    })
+    try { this.emit("socket", sessionId, sock, { listen }) }
+    catch (e) { this._emitError(sessionId, e) }
+  }
+
+  _scheduleReconnect(sessionId, entry, { immediate = false, reason } = {}) {
+    if (entry.timer) return // já há uma reconexão agendada: nunca duas
+    // número que ninguém parou para parear: depois de N quedas seguidas, desiste em vez de recriar o pareamento para sempre
+    const max = this.maxAttemptsWithoutPairing
+    if (!immediate && max && !this._isPaired(entry) && entry.attempts >= max)
+      return this._halt(sessionId, entry, { reason: "gave-up", attempts: entry.attempts }, "gave-up",
+        new Error(`Desisti de conectar "${sessionId}" depois de ${entry.attempts} tentativas sem parear`))
+    entry.status = STATUS.RECONNECTING
+    const delay = immediate ? 0 : this.backoff(entry.attempts++) // reconexão imediata não gasta o backoff
+    this.emit("reconnecting", sessionId, { attempt: entry.attempts, delayMs: delay, reason, immediate })
+    entry.timer = setTimeout(() => {
+      entry.timer = null
+      this._connect(sessionId, true).catch(e => this._emitError(sessionId, e))
+    }, delay)
+  }
+
+  _creationFailure(sessionId, entry, error, isReconnect) {
+    if (!isReconnect) return this._fatalFailure(sessionId, error) // 1ª tentativa: start() rejeita, como antes
+    // reconectando (ex.: sem rede na hora de criar o socket): não morre; avisa e tenta de novo com backoff
+    if (this._sessions.get(sessionId) !== entry || entry.status === STATUS.STOPPED) return
+    this._emitError(sessionId, error)
+    this._scheduleReconnect(sessionId, entry)
+  }
+
+  _fatalFailure(sessionId, error) {
+    const entry = this._sessions.get(sessionId)
+    if (entry) entry.status = STATUS.STOPPED
+    try { this._emitError(sessionId, error) }
+    finally { entry?._rejectFirstConnection?.(error) } // mesmo que um ouvinte lance, o start() não fica pendurado
+  }
+
+  // EventEmitter lança se alguém emite "error" sem ouvinte (e ainda lançaria o 1º argumento, o sessionId):
+  // sem ouvinte, o erro vai para o console em vez de derrubar o processo.
+  _emitError(sessionId, error) {
+    if (this.listenerCount("error") > 0) this.emit("error", sessionId, error)
+    else console.error(`[morpho/pool] erro na sessão "${sessionId}" (ninguém ouvindo o evento "error"):`, error)
+  }
+}
+
+module.exports = { MorphoPool, STATUS, CLOSE_REASONS, DEFAULT_POLICY }

package/packages/pool/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@morpho/pool",
+  "version": "0.1.0",
+  "description": "Gerente de várias sessões de WhatsApp no mesmo processo: conectar, reconectar com backoff, pareamento, parar, resetar. Sem nenhuma regra de negócio (planos, limites) — isso fica por conta de quem usa.",
+  "main": "index.js",
+  "dependencies": { "@morpho/core": "file:../core" },
+  "license": "MIT"
+}

package/packages/presence/README.md

@@ -0,0 +1,40 @@
+# morpho-socket/presence
+
+Two small things that make a bot feel natural.
+
+## 1. "typing…" / "recording audio…" while the bot works
+
+WhatsApp clears the indicator after a few seconds, so it is renewed until the work ends (then `paused` is sent). If the work finishes quickly, nothing shows.
+
+```js
+const { createPresence } = require("morpho-socket/presence")
+const presence = createPresence({ enabled: () => true })   // intervalMs defaults to 7000
+
+await presence.during(sock, jid, "composing", async () => {
+  return await slowThing()
+}, { delayMs: 1200 })                  // only show the indicator if the work takes > 1.2 s
+
+const stop = presence.start(sock, jid, "recording")        // manual form, for when try/finally is easier
+// … later
+stop()
+```
+
+States: `"composing"` (typing) · `"recording"`. `enabled` is read on every call, so you can toggle it at runtime.
+
+## 2. A minimum response delay
+
+The bot only answers after a minimum time **counted from when the message arrived**, not from when the command finished. Works for every command without editing any of them.
+
+```js
+const { createResponseDelay } = require("morpho-socket/presence")
+const delay = createResponseDelay({ delayMs: () => 2000, showTyping: () => true })
+
+delay.install(sock)                    // wraps sendMessage / relayMessage, once per socket
+
+await delay.run(() => handleMessage(msg))              // marks "arrived now" for everything sent inside
+await delay.run(() => handleBatch(m), arrivedAt)       // a batch shares ONE arrival time: the delay doesn't add up
+```
+
+Edits, reactions, deletes and broadcast chats are never delayed. With `showTyping`, the indicator is shown while waiting (`recording` for audio).
+
+Both factories read their settings through functions, so a dashboard can change them without restarting the bot.

package/packages/presence/index.js

@@ -0,0 +1,80 @@
+// @morpho/presence
+//
+// 1) createPresence: "typing…" / "recording audio…" while the bot works. WhatsApp clears the indicator after a few
+//    seconds, so it is renewed until the work ends (then "paused" is sent). If the work ends fast, nothing shows.
+// 2) createResponseDelay: the bot only answers after a minimum time counted from when the message ARRIVED. Works for any
+//    command without editing it (AsyncLocalStorage carries the arrival time).
+const { AsyncLocalStorage } = require("async_hooks")
+
+const INTERVAL_MS = 7000
+
+// opts: { enabled: () => boolean (default true), intervalMs }
+function createPresence({ enabled = () => true, intervalMs = INTERVAL_MS } = {}) {
+  function send(sock, jid, state) {
+    try { Promise.resolve(sock?.sendPresenceUpdate?.(state, jid)).catch(() => {}) } catch { /* presence is decoration */ }
+  }
+
+  // during(sock, jid, "composing" | "recording", fn, { delayMs }): runs fn with the indicator on (only after delayMs)
+  async function during(sock, jid, state, fn, { delayMs = 0 } = {}) {
+    let on = false, wait = null, cycle = null
+    const turnOn = () => { on = true; send(sock, jid, state); cycle = setInterval(() => send(sock, jid, state), intervalMs); cycle.unref?.() }
+    if (state && enabled()) {
+      if (delayMs > 0) { wait = setTimeout(turnOn, delayMs); wait.unref?.() } else turnOn()
+    }
+    try { return await fn() }
+    finally { clearTimeout(wait); clearInterval(cycle); if (on) send(sock, jid, "paused") }
+  }
+
+  // turns the indicator on and returns the function that turns it off (for spots where try/finally is easier)
+  function start(sock, jid, state) {
+    if (!state || !enabled()) return () => {}
+    send(sock, jid, state)
+    const cycle = setInterval(() => send(sock, jid, state), intervalMs)
+    cycle.unref?.()
+    let stopped = false
+    return () => { if (stopped) return; stopped = true; clearInterval(cycle); send(sock, jid, "paused") }
+  }
+
+  return { during, start, send }
+}
+
+// opts: { delayMs: () => number, showTyping: () => boolean }  (read on every send, so they can change at runtime)
+function createResponseDelay({ delayMs = () => 0, showTyping = () => false } = {}) {
+  const als = new AsyncLocalStorage()
+
+  // runs fn marking "the message arrived now" (or at `arrivedAt`) for everything fn sends.
+  // A batch passes the SAME arrivedAt to all messages: the delay doesn't add up message by message.
+  const run = (fn, arrivedAt = Date.now()) => als.run({ arrivedAt }, fn)
+
+  async function wait(sock, jid, content) {
+    if (content?.edit) return // editing a message that already left doesn't wait
+    const ms = Number(delayMs()) || 0
+    const store = als.getStore()
+    if (!ms || !store || String(jid).includes("broadcast")) return
+    const missing = store.arrivedAt + ms - Date.now()
+    if (missing <= 0) return
+    const isMessage = content && !content.react && !content.delete && !content.protocolMessage
+    if (showTyping() && isMessage) {
+      try { Promise.resolve(sock.sendPresenceUpdate?.(content.audio ? "recording" : "composing", jid)).catch(() => {}) } catch { /* decoration */ }
+    }
+    await new Promise(r => setTimeout(r, missing))
+  }
+
+  // wraps sendMessage/relayMessage of the socket (once per socket)
+  function install(sock) {
+    if (sock.__morphoDelay) return sock
+    sock.__morphoDelay = true
+    const send = sock.sendMessage.bind(sock)
+    sock.sendMessage = async (jid, content, opts) => { await wait(sock, jid, content); return send(jid, content, opts) }
+    if (typeof sock.relayMessage === "function") {
+      const relay = sock.relayMessage.bind(sock)
+      // interactive menus use relayMessage directly; Baileys' sendMessage calls the internal relay, so it isn't counted twice
+      sock.relayMessage = async (jid, msg, opts) => { await wait(sock, jid, msg); return relay(jid, msg, opts) }
+    }
+    return sock
+  }
+
+  return { run, install, wait }
+}
+
+module.exports = { createPresence, createResponseDelay, INTERVAL_MS }

package/packages/presence/package.json

@@ -0,0 +1 @@
+{ "name": "@morpho/presence", "version": "0.1.0", "description": "'typing...' / 'recording audio...' while the bot works (renewed until done) and a minimum response delay measured from when the message ARRIVED.", "main": "index.js", "license": "MIT" }

package/packages/reply/README.md

@@ -0,0 +1,36 @@
+# morpho-socket/reply
+
+Reply on WhatsApp **quoting the original message without losing its mentions**, plus the small "send something as a reply" helpers every bot rewrites.
+
+**The problem:** when Baileys quotes a message that mentions someone, it drops the original `contextInfo`, so the quoted bubble shows a raw `@lid` / number instead of the person's name. Morpho builds the quote by hand and carries the mentions along.
+
+```js
+const reply = require("morpho-socket/reply")
+
+await reply.reply(sock, jid, msg, "hello")                          // quotes msg, keeps its mentions
+await reply.replyImage(sock, jid, msg, buffer, { caption: "look" })
+await reply.replyGif(sock, jid, msg, videoBuffer, { caption, mentions })
+await reply.sendVoice(sock, jid, mp3Buffer, { quoted: msg })        // converts to ogg/opus (needs ffmpeg)
+await reply.sendSticker(sock, jid, webpBuffer, { quoted: msg })
+await reply.react(sock, msg, "🎉")
+await reply.sendPoll(sock, jid, "Pizza?", ["yes", "no"])
+```
+
+`reply()` also notices when your text repeats the `@number` of someone the original message mentioned, and turns it into a real mention: if someone sends `!chance of @ana becoming admin` and the bot answers `@ana has 42%…`, WhatsApp shows her name (clickable) instead of the number.
+
+## API
+
+| | |
+|---|---|
+| `reply(sock, jid, msg, text, extra?)` | text reply; keeps and extends mentions |
+| `replyWithMentions(sock, jid, msg, text, mentions, extra?)` | explicit mentions |
+| `sendQuoted(sock, jid, msg, content, { always }?)` | **any** content (text, image…) quoting `msg`; the manual quote is used only when the original mentions someone (or with `always`) |
+| `replyImage` / `replyGif` / `replyMedia` | media quoting the original. If sending fails (corrupt file, too large) it falls back to a text reply instead of staying silent (`onError` is called) |
+| `replySticker(sock, jid, msg, webp)` | sticker, always quoted |
+| `sendSticker(sock, jid, webp, { quoted }?)` | sticker to any chat; quotes only if asked |
+| `sendVoice(sock, jid, audio, { quoted, convert }?)` | voice note. WhatsApp only plays PTT as ogg/opus, so other formats are converted; pass `convert: false` if the buffer is already ogg/opus |
+| `react(sock, msg, emoji)` · `sendPoll(sock, jid, question, options, { selectableCount }?)` | |
+| `toOggOpus(buffer, { ffmpeg, timeoutMs }?)` | audio → ogg/opus using the `ffmpeg` binary |
+| `buildQuoteContext(sock, msg, mentions)` · `mentionsOf(msg)` · `stripDevice(jid)` | building blocks |
+
+> Using [`context`](../context)? `g.reply()` already does all of this — you rarely call this module directly.