morpho-socket 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# morpho-socket
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Building blocks for WhatsApp bots, on top of [Baileys](https://github.com/WhiskeySockets/Baileys).
+
+Baileys speaks the WhatsApp protocol. **Morpho takes care of everything around it** — the parts every serious bot ends up rewriting: running several numbers in one process, knowing who actually sent a message (LID → phone number), replying without losing mentions, downloading media whose link expired, caching group metadata, loading commands from folders, and keeping bot data safe in SQLite.
+
+Every piece is a small, independent module. Use the whole stack, or only the parts you need.
+
+```bash
+npm install morpho-socket @whiskeysockets/baileys
+```
+
+> **Unofficial.** Morpho is not affiliated with, endorsed by, or connected to WhatsApp or Meta. Automating WhatsApp accounts can violate its Terms of Service; use it at your own risk and respect people's privacy.
+
+## Requirements
+
+- **Node.js ≥ 22.5** (`store-sqlite` and `kv` use the built-in `node:sqlite`)
+- **Baileys** installed in your own project (Morpho loads it from there; it is not bundled)
+- **ffmpeg** on the `PATH`, only if you send voice notes from non-Opus audio
+
+Morpho is CommonJS.
+
+## What problems does it solve?
+
+| Problem | Module |
+|---|---|
+| One folder full of loose JSON files per client | [`store-sqlite`](packages/store-sqlite) — every session in one `.sqlite` file |
+| Several numbers in one process: pairing, reconnecting, banned/replaced sessions | [`pool`](packages/pool) |
+| "Who sent this?" — the message carries a `@lid`, not a phone number | [`jid`](packages/jid) |
+| The real message is buried under `ephemeralMessage`, `viewOnceMessageV2`, `editedMessage`… | [`message`](packages/message) |
+| Replying to a message that mentions someone shows a raw `@123…` in the quote | [`reply`](packages/reply) |
+| "Is the sender an admin?" hits WhatsApp on every message | [`groups`](packages/groups) |
+| Media download fails because the CDN link expired | [`media`](packages/media) |
+| Native buttons and lists (Baileys has no helper) | [`interactive`](packages/interactive) |
+| "typing…" indicators and a minimum response delay | [`presence`](packages/presence) |
+| Re-sending undecryptable messages / opening poll votes | [`sent`](packages/sent) |
+| One object with everything about the current message | [`context`](packages/context) |
+| Commands from folders, aliases, admin/owner guards, antiflood | [`commands`](packages/commands) |
+| Bot data (economy, settings, cooldowns) with real transactions | [`kv`](packages/kv) |
+
+## A quick look
+
+The whole stack wired together — a multi-number bot with one command:
+
+```js
+const path                  = require("path")
+const { initAuthCreds }     = require("@whiskeysockets/baileys")
+const { MorphoPool }        = require("morpho-socket/pool")
+const sqlite                = require("morpho-socket/store-sqlite")
+const { createIdentity }    = require("morpho-socket/jid")
+const { createGroups }      = require("morpho-socket/groups")
+const { createSentStore }   = require("morpho-socket/sent")
+const { createMedia }       = require("morpho-socket/media")
+const { createContext }     = require("morpho-socket/context")
+const { createCommands }    = require("morpho-socket/commands")
+
+const store    = sqlite.create({ path: "./data/sessions.sqlite" })
+const identity = createIdentity({ store })          // the LID → number map survives restarts
+
+const contexts = createContext({
+  identity,
+  media: createMedia(),
+  prefix: "!",
+  isOwner: g => g.user.phone === "5511999999999",   // your rules plug in here
+})
+
+const commands = createCommands({ dirs: [{ type: "user", dir: path.join(__dirname, "commands", "user") }], log: console.log })
+commands.load()
+
+// groups + sent are per socket, so keep them per session
+const perSession = new Map()
+const pool = new MorphoPool({
+  store,
+  initCreds: initAuthCreds,
+  socketConfig: sessionId => {                      // extra options for Baileys' makeWASocket
+    const groups = createGroups(), sent = createSentStore()
+    perSession.set(sessionId, { groups, sent })
+    return { cachedGroupMetadata: groups.cachedGroupMetadata, getMessage: key => sent.get(key) }
+  },
+})
+
+// the pool hands you a fresh socket on every (re)connection
+pool.on("socket", (sessionId, sock, { listen }) => {
+  const { groups, sent } = perSession.get(sessionId)
+  groups.install(sock)                              // cached group metadata + admin checks
+  sent.install(sock)                                // remembers what the bot sent
+  identity.install(sock, sessionId)                 // learns LID ↔ number from socket events
+
+  listen("messages.upsert", async ({ type, messages }) => {
+    if (type !== "notify") return
+    for (const msg of messages) {
+      const g = await contexts.build({ sock, msg, clientId: sessionId })
+      await commands.dispatch(g)
+    }
+  })
+})
+
+pool.on("pairing-code", (id, code) => console.log(`${id}: enter ${code} on the phone`))
+pool.on("logged-out",   id => console.log(`${id} was logged out`))
+
+await pool.startAll([{ sessionId: "my-bot", phoneNumber: "5511999999999" }])
+```
+
+```js
+// commands/user/ping.js
+module.exports = {
+  name: "ping",
+  aliases: ["p"],
+  async run(g) {
+    await g.reply(`pong, ${g.user.name}`)
+  },
+}
+```
+
+## How the pieces fit
+
+```
+                      ┌────────────── Baileys (WhatsApp protocol) ──────────────┐
+                      │                                                         │
+ store-sqlite/file ──▶ core ──▶ pool  ── "socket" event ──▶ messages.upsert     │
+ (where sessions live)  (auth)   (many numbers, reconnect)        │             │
+                                                                  ▼             │
+                                          message.parse + jid (who sent it?)    │
+                                                                  │             │
+                                              context  ──▶  `g` (one object)    │
+                                                                  │             │
+                                     commands.dispatch ──▶ your command.run(g)  │
+                                                                  │             │
+                       reply · media · interactive · presence ◀───┘             │
+                       groups (cache) · sent (getMessage) · kv (your data)      │
+                      └─────────────────────────────────────────────────────────┘
+```
+
+## Design principles
+
+- **No business rules inside.** Plans, limits, who the owner is, what "banned" means — that is your bot. Morpho exposes hooks and events.
+- **Expected failures are values, not exceptions.** `g.kick()` returns `{ ok: false, reason: "target-is-admin" }`; media errors carry a stable `.code`; identity never throws (a message is never lost because a lookup failed).
+- **Morpho never writes user-facing text for you.** It gives you stable reason codes; you decide what to say (and in which language).
+- **Plain data in, plain data out.** `message.parse()` returns a simple object; `g.who()` returns a `Person`; stores are six-method duck-typed objects.
+- **Everything is injectable and testable without WhatsApp.** Sockets, downloaders and clocks can be replaced, so the whole suite runs with mocks.
+
+## Documentation
+
+- **[Building a bot with Morpho](docs/building-a-bot.md)** — a tour of every feature and how to combine them.
+- Each module has its own README with the full API:
+  [`core`](packages/core) · [`store-sqlite`](packages/store-sqlite) · [`store-file`](packages/store-file) · [`pool`](packages/pool) · [`message`](packages/message) · [`jid`](packages/jid) · [`groups`](packages/groups) · [`media`](packages/media) · [`reply`](packages/reply) · [`interactive`](packages/interactive) · [`presence`](packages/presence) · [`sent`](packages/sent) · [`context`](packages/context) · [`commands`](packages/commands) · [`kv`](packages/kv)
+
+## Testing
+
+```bash
+npm test      # every suite, no WhatsApp connection needed
+```
+
+## License
+
+MIT. Built on top of Baileys (MIT); Morpho does not reimplement any part of the WhatsApp protocol.

package/docs/building-a-bot.md

@@ -0,0 +1,402 @@
+# Building a bot with Morpho
+
+A tour of what Morpho gives you and how the pieces combine. This is not a "from zero" tutorial — it assumes you know what a WhatsApp bot is and want to see what you can build with each part. Every module has its own README with the full API; this guide shows how they fit together.
+
+- [The mental model](#the-mental-model)
+- [Sessions: many numbers, one process](#sessions-many-numbers-one-process)
+- [Understanding incoming messages](#understanding-incoming-messages)
+- [The `g` context](#the-g-context)
+- [Commands](#commands)
+- [Replying and sending](#replying-and-sending)
+- [Managing groups](#managing-groups)
+- [Media](#media)
+- [Buttons and lists](#buttons-and-lists)
+- [Feeling natural: presence and delays](#feeling-natural-presence-and-delays)
+- [Resilience](#resilience)
+- [Your bot's data](#your-bots-data)
+- [Putting it together](#putting-it-together)
+- [Production notes](#production-notes)
+
+## The mental model
+
+Baileys owns the connection. Morpho owns the plumbing between "a socket exists" and "your command runs":
+
+```
+store ──▶ pool ──▶ socket ──▶ messages.upsert
+(sessions) (numbers)             │
+                                 ▼
+                     message.parse  +  jid.resolveSender
+                                 │
+                     context.build ──▶ g
+                                 │
+                     commands.dispatch ──▶ your command.run(g)
+                                 │
+                     g.reply · g.kick · g.download · …
+```
+
+Each arrow is a separate module you can replace or skip. You can use `message` and `jid` inside a hand-written handler without ever touching `commands`, or use `pool` with your own message logic.
+
+Morpho has **no business rules**. Who the owner is, what a plan includes, which groups are enabled — those are yours, plugged in through options and hooks.
+
+## Sessions: many numbers, one process
+
+**Where sessions live** is a one-line choice. `store-sqlite` keeps every client in a single `.sqlite` file; `store-file` keeps one folder per client (a bridge if you come from `useMultiFileAuthState`). Writing your own backend is six methods ([`core`](../packages/core)).
+
+**How they run** is [`pool`](../packages/pool):
+
+```js
+const pool = new MorphoPool({ store, initCreds: initAuthCreds })
+await pool.startAll(["client-a", { sessionId: "client-b", phoneNumber: "5511999999999" }])
+```
+
+- A session with no saved credentials and a `phoneNumber` gets a **pairing code** (`pool.on("pairing-code", …)`).
+- Drops are handled by policy: network errors reconnect with backoff, `515` (restart after pairing) reconnects immediately, and `401` logged-out, `403` banned/restricted and `440` replaced stop for good — retrying those only makes things worse. Each one has its own event so you can notify the client.
+- `stop(id)` keeps the session; `reset(id)` deletes it. `info(id)` / `list()` feed a dashboard.
+- `maxAttemptsWithoutPairing` stops a number nobody ever paired from retrying forever (`gave-up`).
+
+The per-socket hook is the `socket` event. It fires on **every** (re)connection with a brand-new socket, and hands you a safe `listen`:
+
+```js
+pool.on("socket", (sessionId, sock, { listen }) => {
+  listen("messages.upsert", async data => { /* errors here go to pool "error", never crash the process */ })
+})
+```
+
+## Understanding incoming messages
+
+Two modules turn raw Baileys data into something you can reason about.
+
+**[`message`](../packages/message)** — `parse(msg)` unwraps view-once, ephemeral, edited and caption wrappers and returns one flat shape: `type`, `text`, `mentions`, `media`, `quoted`, `selection` (button taps), `reaction`, `edited`/`revoked`…
+
+```js
+const m = parse(msg)
+if (m.is("image", "video") && m.text.startsWith("!sticker")) { /* … */ }
+if (m.quoted?.media) { /* the user replied to a media message */ }
+```
+
+**[`jid`](../packages/jid)** — answers "who is this, really?". WhatsApp may deliver a LID instead of a phone number; `resolveSender` always returns the clean number (or `null`, with the `source` of the answer), using the cheapest source first and learning as it goes. Pass it a store and what it learns survives restarts.
+
+```js
+const who = await identity.resolveSender(msg, sock, clientId)
+who.number      // "5511968111161"   — your database key
+who.formatted   // "+55 (11) 96811-1161"
+```
+
+## The `g` context
+
+[`context`](../packages/context) combines the above into the single object every command receives. You build it once per message:
+
+```js
+const g = await contexts.build({ sock, msg, clientId })
+```
+
+| You want | You write |
+|---|---|
+| the text / the command / its arguments | `g.text` · `g.command` · `g.args` · `g.argText` |
+| who sent it | `g.user.number` (never empty — your DB key) · `g.user.phone` · `g.user.name` |
+| who it's about | `await g.who()` — the mentioned person, else the replied-to author |
+| permissions | `g.isOwner` · `await g.isAdmin()` · `await g.isBotAdmin()` |
+| to answer | `g.reply(…)` · `g.send(jid, …)` · `g.react("👍")` · `g.edit(sent, …)` |
+| group info and actions | `g.group()` · `g.members()` · `g.kick()` · `g.promote()` · … |
+| media | `g.download()` · `g.media()` |
+
+Your bot's rules plug in through `createContext` options and `extend`:
+
+```js
+const contexts = createContext({
+  identity, media, interactive,
+  prefixFor: (g, chatId) => settings.get(`${g.clientId}/${chatId}/prefix`, "!"),   // per-group prefix
+  isOwner: g => OWNERS.has(g.user.number),
+  protect: (g, person) => OWNERS.has(person.number),                               // g.kick() will refuse
+  extend: {
+    get plan() { return clients.get(this.clientId)?.plan ?? "free" },              // g.plan in every command
+  },
+})
+```
+
+Extra properties passed to `build()` are copied onto `g` too — handy for handing commands your database handle.
+
+## Commands
+
+[`commands`](../packages/commands) is the generic half of a command bot. Commands are files:
+
+```
+commands/
+  user/
+    ping.js
+    economy/
+      balance.js        → category "economy"
+  admin/
+    ban.js              → needs: group + admin sender + admin bot
+  owner/
+    broadcast.js        → needs: g.isOwner
+```
+
+```js
+// commands/admin/ban.js
+module.exports = {
+  name: "ban",
+  aliases: ["kick"],
+  async run(g) {
+    const r = await g.kick()
+    if (!r.ok) return g.reply(ERRORS[r.reason] ?? ERRORS.failed)
+    await g.reply(`Removed ${await g.at(r.jid)}`)
+  },
+}
+```
+
+What the loader gives you for free: aliases, categories from folders, `_helper.js` / `*.test.js` ignored, and **warnings** for repeated names, a mistyped `aliasee`, broken files and commands missing `name`/`run` — one broken file never stops the rest.
+
+Everything that is your business goes into `dispatch` hooks:
+
+```js
+await commands.dispatch(g, {
+  before: async (g, command) => {
+    if (!settings.isEnabled(g, command)) return false          // per-group switch
+    const flood = antiflood.check(`${g.clientId}:${g.user.number}`, floodConfig)
+    if (!flood.ok) { if (flood.warn) await g.reply(`Slow down (${flood.wait}s)`); return false }
+  },
+  onNotFound: async (g, { name }) => suggestSimilar(g, name),  // "did you mean…?"
+  run: (g, command, args, exec) =>                              // wrap execution: typing indicator, timing, stats
+    presence.during(g.sock, g.chatId, "composing", exec, { delayMs: 1200 }),
+})
+```
+
+## Replying and sending
+
+One door: `g.reply()` for the current chat, `g.send(jid, …)` for any other.
+
+```js
+await g.reply("text")                                      // quotes the command, keeps mentions
+await g.reply({ image: buffer, caption: "look" })          // image | video | gif | sticker | voice | audio | document
+await g.reply(`congrats ${await g.at(person)}!`)           // a real, clickable mention
+const sent = await g.reply("working…")
+await g.edit(sent, "done")                                 // edit your own message
+await g.poll("Pizza?", ["yes", "no"])
+```
+
+Details you don't have to handle:
+
+- **Mentions survive quoting.** Baileys drops the original mentions when quoting, which shows a raw `@123…` in the bubble; Morpho rebuilds the quote ([`reply`](../packages/reply)).
+- **`g.at(person)`** writes the `@id` into your text *and* registers the mention, using the participant's native id so WhatsApp swaps it for their name.
+- **A command is never mute.** If quoting fails it sends without the quote; if media fails and there's a caption, the caption is sent.
+- Media sources can be a `Buffer`, a URL, a file path or `{ url }`. Voice notes are converted to ogg/opus with ffmpeg.
+
+## Managing groups
+
+Every group action has the same shape and **never throws**:
+
+```js
+const r = await g.kick(["5511911111111", "5511922222222"])   // one WhatsApp call for many people
+// → { ok: false, action: "kick", results: [{ ok: true, … }, { ok: false, reason: "target-is-admin", … }] }
+```
+
+You get a stable `reason` and decide what to tell the user (and in which language) — Morpho never writes user-facing text:
+
+```js
+const ERRORS = {
+  "bot-not-admin": "Make me an admin first.",
+  "target-is-admin": "I won't remove an admin.",
+  "not-in-group": "That person isn't in this group.",
+  failed: "Something went wrong.",
+}
+```
+
+Available: `kick` `promote` `demote` `add` `approve` `reject` · `close` `open` `lock` `unlock` `rename` `setDescription` `leave` · `link` `revokeLink` · `delete`. Safe defaults protect the bot, the group creator and admins; `protect` adds your own untouchables. `add` returns `needs-invite` with the invite link when privacy settings block a direct add.
+
+Behind the scenes [`groups`](../packages/groups) keeps this fast: metadata is cached with a TTL, simultaneous lookups collapse into one, stale data is served when WhatsApp refuses, and the cache is dropped the moment a group changes.
+
+## Media
+
+**Receiving.** `g.download()` finds the media (the replied-to message wins, so `!sticker` as a reply to an image works), downloads it with a size limit, timeout, retry and cache, and returns a `Buffer` or `null`.
+
+```js
+const buffer = await g.download({ types: ["image"], max: 10 * 1024 * 1024 })
+if (!buffer) return g.reply("Send or reply to an image.")
+```
+
+When WhatsApp's CDN link has expired, [`media`](../packages/media) asks the phone to re-send the file once and downloads again — the case that makes most bots answer "couldn't download". Errors have stable codes (`MEDIA_TOO_LARGE`, `MEDIA_EXPIRED`, `MEDIA_TIMEOUT`…) so you can answer sensibly.
+
+Privacy defaults: view-once media is never returned unless asked (`viewOnce: true`) and never cached; the optional disk cache is `0700`/`0600` with an expiry.
+
+**Sending.** `g.reply({ image | video | gif | sticker | voice | audio | document })` — see above.
+
+## Buttons and lists
+
+Native buttons and selection lists work through [`interactive`](../packages/interactive):
+
+```js
+const ui = createInteractive({ mark: "mybot:" })          // the same instance you pass to createContext
+
+await g.reply({
+  body: "What next?",
+  image: menuImage, imageId: "menu",                      // upload reused for 6 hours
+  buttons: [
+    ui.button.reply("Games", "menu games"),
+    ui.button.link("Website", "https://example.com"),
+    ui.button.list("More", [ui.section("Fun", [ui.row("Dice", "roll a die", "dice")])]),
+  ],
+  fallback: "Reply with !menu games or !dice",           // used if the interactive send fails
+})
+```
+
+A tap arrives as ordinary text (`g.text === "menu games"`), so your commands handle it exactly like a typed command. Taps on another bot's menu in the same group are ignored. This feature relies on undocumented WhatsApp behavior — keep the `fallback`.
+
+## Feeling natural: presence and delays
+
+[`presence`](../packages/presence) does two things:
+
+- `during(sock, jid, "composing", fn, { delayMs })` shows "typing…" while `fn` runs (renewed until it ends; skipped if it finishes before `delayMs`).
+- `createResponseDelay` enforces a minimum answer time **measured from when the message arrived**, for every command, without touching any of them.
+
+```js
+const delay = createResponseDelay({ delayMs: () => settings.delayMs, showTyping: () => true })
+delay.install(sock)
+await delay.run(() => handle(msg))
+```
+
+Both read their settings through functions, so a dashboard can change them live.
+
+## Resilience
+
+Small things that stop bots from failing silently:
+
+- **[`sent`](../packages/sent)** — remembers what you sent so Baileys' `getMessage` can re-send undecryptable messages and open poll votes.
+- **[`groups`](../packages/groups)** — cached metadata means group sends and admin checks don't hammer WhatsApp.
+- **[`pool`](../packages/pool)** — caches the protocol version (with a timeout and fallback), spreads out `startAll`, never recreates a half-finished pairing, and turns listener errors into events instead of crashes.
+- **Identity never throws** — a message is never lost because a LID lookup failed.
+
+## Your bot's data
+
+[`kv`](../packages/kv) is a single SQLite file for everything that isn't a WhatsApp session:
+
+```js
+const db = openKV("data/bot.sqlite")
+const eco = db.collection("economy")
+
+db.transaction(() => {                                    // all-or-nothing transfer
+  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 }))
+})
+
+db.collection("cooldowns").set(`${g.user.number}:daily`, true, { ttl: 24 * 3600e3 })   // expires by itself
+eco.top("coins", { limit: 10 })                           // leaderboard
+const perGroup = db.collection("settings").sub(g.clientId, g.chatId)                   // isolated per client and group
+```
+
+Use `g.user.number` as the person key and `sub(clientId, chatId)` for per-group data, so clients never see each other's data.
+
+## Putting it together
+
+A complete, multi-number bot. Everything marked "yours" is where your own rules go.
+
+```js
+// index.js
+const path                = require("path")
+const { initAuthCreds }   = require("@whiskeysockets/baileys")
+const { MorphoPool }      = require("morpho-socket/pool")
+const sqlite              = require("morpho-socket/store-sqlite")
+const { createIdentity }  = require("morpho-socket/jid")
+const { createGroups }    = require("morpho-socket/groups")
+const { createSentStore } = require("morpho-socket/sent")
+const { createMedia }     = require("morpho-socket/media")
+const { createInteractive } = require("morpho-socket/interactive")
+const { createPresence }  = require("morpho-socket/presence")
+const { createContext }   = require("morpho-socket/context")
+const { createCommands, createAntiflood } = require("morpho-socket/commands")
+const { openKV }          = require("morpho-socket/kv")
+
+const store    = sqlite.create({ path: "./data/sessions.sqlite" })
+const db       = openKV("./data/bot.sqlite")
+const identity = createIdentity({ store })
+const presence = createPresence()
+const antiflood = createAntiflood()
+const ui       = createInteractive({ mark: "mybot:" })
+
+const contexts = createContext({
+  identity,
+  media: createMedia({ disk: { dir: "./data/media-cache" } }),
+  interactive: ui,
+  prefix: "!",
+  isOwner: g => g.user.phone === process.env.OWNER_NUMBER,        // yours
+  extend: { db },                                                 // yours: g.db in every command
+})
+
+const commands = createCommands({
+  dirs: [
+    { type: "user",  dir: path.join(__dirname, "commands", "user")  },
+    { type: "admin", dir: path.join(__dirname, "commands", "admin") },
+    { type: "owner", dir: path.join(__dirname, "commands", "owner") },
+  ],
+  log: (level, text) => console[level === "error" ? "error" : "log"](text),
+})
+commands.load()
+
+// groups + sent are per socket, so keep them per session
+const perSession = new Map()
+
+const pool = new MorphoPool({
+  store,
+  initCreds: initAuthCreds,
+  maxAttemptsWithoutPairing: 8,
+  socketConfig: sessionId => {
+    const groups = createGroups(), sent = createSentStore()
+    perSession.set(sessionId, { groups, sent })
+    return { cachedGroupMetadata: groups.cachedGroupMetadata, getMessage: key => sent.get(key) }
+  },
+})
+
+pool.on("socket", (sessionId, sock, { listen }) => {
+  const { groups, sent } = perSession.get(sessionId)
+  groups.install(sock)
+  sent.install(sock)
+  identity.install(sock, sessionId)
+
+  listen("messages.upsert", async ({ type, messages }) => {
+    if (type !== "notify") return
+    for (const msg of messages) {
+      if (msg.key.fromMe) continue
+      const g = await contexts.build({ sock, msg, clientId: sessionId })
+
+      await commands.dispatch(g, {
+        before: async () => {
+          const f = antiflood.check(`${sessionId}:${g.user.number}`, { enabled: true, commands: 5, windowSec: 10, blockSec: 30 })
+          if (!f.ok) { if (f.warn) await g.reply(`Slow down — wait ${f.wait}s`); return false }
+        },
+        onNotFound: async () => {},                                // yours: "did you mean…?"
+        run: (g, command, args, exec) => presence.during(sock, g.chatId, "composing", exec, { delayMs: 1200 }),
+      })
+    }
+  })
+})
+
+pool.on("connect",      id => console.log(`${id} connected`))
+pool.on("pairing-code", (id, code) => console.log(`${id}: enter ${code} on the phone`))
+pool.on("logged-out",   id => console.log(`${id} was logged out — pair again`))
+pool.on("replaced",     id => console.log(`${id} was opened somewhere else`))
+pool.on("error",        (id, e) => console.error(id, e))
+
+pool.startAll([{ sessionId: "main", phoneNumber: process.env.BOT_NUMBER }])
+```
+
+Suggested layout:
+
+```
+my-bot/
+  index.js
+  commands/
+    user/      ping.js  economy/balance.js …
+    admin/     ban.js  close.js …
+    owner/     broadcast.js …
+  data/        sessions.sqlite  bot.sqlite  media-cache/     # keep out of git and backups
+```
+
+## Production notes
+
+- **One process per session.** Opening the same session from two processes gets one of them kicked (`440` → `replaced`). Running several *different* numbers in one process is what the pool is for.
+- **Back up `data/`** — `db.backup("backup.sqlite")` gives a consistent copy of the bot database while it runs. The session store holds credentials: treat it like a password.
+- **Keep the media disk cache private.** It stores decrypted files; keep it out of backups and zips.
+- **Spread out startup.** `pool.startAll(items, { intervalMs })` opens connections one after another rather than all at once.
+- **Always give interactive messages a `fallback`.**
+- **ffmpeg** must be on the `PATH` to send voice notes from non-Opus audio.
+- **Node ≥ 22.5** is required by `store-sqlite` and `kv`. They print an `ExperimentalWarning` from Node itself; it is harmless.

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "morpho-socket",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Blocos para bots de WhatsApp sobre o Baileys",
+  "license": "MIT",
+  "engines": { "node": ">=22.5.0" },
+  "peerDependencies": { "@whiskeysockets/baileys": "*" },
+  "files": ["packages", "README.md", "docs"],
+  "exports": {
+    "./core": "./packages/core/index.js",
+    "./store-sqlite": "./packages/store-sqlite/index.js",
+    "./store-file": "./packages/store-file/index.js",
+    "./pool": "./packages/pool/index.js",
+    "./message": "./packages/message/index.js",
+    "./jid": "./packages/jid/index.js",
+    "./groups": "./packages/groups/index.js",
+    "./media": "./packages/media/index.js",
+    "./reply": "./packages/reply/index.js",
+    "./interactive": "./packages/interactive/index.js",
+    "./presence": "./packages/presence/index.js",
+    "./sent": "./packages/sent/index.js",
+    "./context": "./packages/context/index.js",
+    "./commands": "./packages/commands/index.js",
+    "./kv": "./packages/kv/index.js"
+  },
+  "scripts": { "test": "node test/run-all.js" }
+}

package/packages/commands/README.md

@@ -0,0 +1,78 @@
+# morpho-socket/commands
+
+The generic half of a command bot: **load commands from folders**, find them by name or alias, run them with the usual guards (owner / admin / bot-admin), and hook in everything that is your bot's own business (per-group switches, antiflood, "did you mean…", stats).
+
+```js
+const path = require("path")
+const { createCommands } = require("morpho-socket/commands")
+
+const commands = createCommands({
+  dirs: [                                       // use absolute paths: each file is loaded with require()
+    { type: "user",  dir: path.join(__dirname, "commands", "user")  },
+    { type: "admin", dir: path.join(__dirname, "commands", "admin") },
+    { type: "owner", dir: path.join(__dirname, "commands", "owner") },
+  ],
+  log: (level, text) => console.log(level, text),
+  messages: { notAdmin: "You are not an admin here.", botNotAdmin: "I need to be an admin.", notOwner: "Owner only.", notGroup: "Groups only." },
+})
+commands.load()   // warns about: repeated names/aliases, a mistyped "aliasee" key, broken files, commands without name/run
+
+await commands.dispatch(g, {                     // the command comes from g.command (the group's prefix is already applied)
+  before:     async (g, command, parsed) => { /* per-group switches, antiflood… return false to stop */ },
+  onNotFound: async (g, parsed) => { /* "unknown command" */ },
+  run:        (g, command, args, exec) => presence.during(g.sock, g.chatId, "composing", exec, { delayMs: 1200 }),
+})
+```
+
+`dispatch` returns `true` when the text was a command call (found or not) and `false` when it wasn't, so you can route non-commands elsewhere.
+
+## A command
+
+```js
+// commands/user/economy/balance.js
+module.exports = {
+  name: "balance",
+  aliases: ["bal", "coins"],
+  access: "user",                       // "user" | "admin" | "owner" — optional, falls back to the folder's `type`
+  desc: "Shows your coins",             // any extra field is kept (desc, usage, cooldown…) for your own use
+  async run(g, { name, args, argText }) {
+    await g.reply("You have 10 coins")
+  },
+}
+```
+
+- **Folders become categories:** `economy/balance.js` → `command.category = "economy"` (top-level files are `"general"`).
+- Files starting with `_` and `*.test.js` are ignored (helpers and tests can live next to commands).
+- A command's own `access` wins over the folder `type`.
+- `admin` requires a group, an admin sender **and** an admin bot; `owner` requires `g.isOwner`. The texts are configurable through `messages` (`notGroup`, `botNotAdmin`, `notAdmin`, `notOwner`).
+- One broken file never stops the others from loading.
+
+## Parsing text yourself
+
+```js
+const { parse } = require("morpho-socket/commands")
+parse("!Hi  a  b", "!")        // { name: "hi", args: ["a", "b"], argText: "a  b", prefix: "!" }
+
+await commands.dispatch(g, { text: "!hi", prefix: "!" })   // parse something other than g.command
+```
+
+## Antiflood
+
+More than N commands in X seconds → the person is ignored for Y seconds. The warning goes out **once per block**; everything else is silently ignored.
+
+```js
+const { createAntiflood } = require("morpho-socket/commands")
+const flood = createAntiflood()
+
+// inside `before`:
+const r = flood.check(`${g.clientId}:${g.user.number}`, { enabled: true, commands: 5, windowSec: 10, blockSec: 30 })
+if (!r.ok) { if (r.warn) await g.reply(`Slow down — wait ${r.wait}s`); return false }
+```
+
+`check` returns `{ ok, warn?, wait?, fresh? }`. Idle entries are cleaned up automatically.
+
+## API
+
+`createCommands({ dirs, log, messages })` → `{ load, dispatch, parse, get(name), has(name), unique(), map, size }` — `unique()` is the real commands (the map holds every name *and* alias).
+
+Also exported: `createAntiflood`, `parse`, `DEFAULT_MESSAGES`. `g` comes from [`context`](../context), but anything with `isOwner`, `isAdmin()`, `isBotAdmin()` and `reply()` works.