morpho-socket 0.3.0 → 0.4.1

package/packages/capture/index.js

@@ -0,0 +1,327 @@
+// @morpho/capture
+//
+// Records what Baileys DELIVERS and what Morpho UNDERSTANDS, so a change on the WhatsApp side (like the move to @lid)
+// shows up as an alert instead of as a bot that silently stopped working.
+//
+// Rules this module never breaks:
+//   - It never throws into the bot: every listener is wrapped, a capture bug is swallowed (and counted).
+//   - It never writes message text, credentials, keys, QR codes or binary content. Strings are replaced by "<str:N>"
+//     unless they are a JID (masked) or a short enum-like field (type, action, connection...).
+//   - Numbers are masked with a keyed hash (same number -> same fake number, so "who is who" still works in the log).
+//
+//   const { createCapture } = require("morpho-socket/capture")
+//   const capture = createCapture({ dir: "./capture", baileysVersion: "7.0.0-rc14" })
+//   capture.attachPool(pool)                       // or capture.attach(sock, { sessionId })
+//   // ... later
+//   console.log(capture.reportText())
+//   capture.exportFixtures("./test/fixtures/lid.json")
+
+const fs = require("node:fs")
+const path = require("node:path")
+const crypto = require("node:crypto")
+
+const EVENTS = [
+  "messages.upsert", "messages.update", "lid-mapping.update", "group-participants.update", "groups.upsert",
+  "groups.update", "contacts.upsert", "contacts.update", "connection.update", "call"
+]
+const FRAME_TAGS = ["message", "notification", "call"]
+const KEEP_KEYS = new Set(["type", "action", "connection", "tag", "addressingMode", "addressing_mode", "reason", "admin", "fromMe", "status", "stubType", "messageStubType"])
+const KEEP_ATTRS = new Set(["type", "addressing_mode", "category", "offline", "mediatype", "edit", "count", "t", "xmlns", "class"])
+const DROP_KEYS = new Set(["qr", "creds", "keys", "authState", "noiseKey", "signedIdentityKey", "advSecretKey"])
+const JID_RE = /^([\w:.\-]+)@(s\.whatsapp\.net|c\.us|lid|hosted|hosted\.lid|g\.us|broadcast|newsletter|call|bot)$/
+const MAX_DEPTH = 5
+const MAX_ITEMS = 8
+
+const isLid = j => typeof j === "string" && /@(hosted\.)?lid$/.test(j)
+const isGroup = j => typeof j === "string" && j.endsWith("@g.us")
+const isSpecial = j => typeof j === "string" && /@(broadcast|newsletter)$/.test(j)
+const isBin = v => Buffer.isBuffer(v) || v instanceof Uint8Array
+
+function createCapture(opts = {}) {
+  const {
+    dir = "./capture", maxBytes = 1_000_000, mask = true,
+    events = EVENTS, frameTags = FRAME_TAGS, console: consoleMode = "alerts", flushMs = 300
+  } = opts
+  let baileysVersion = opts.baileysVersion || null
+  if (!baileysVersion) {
+    try { baileysVersion = require("../core/baileys").loadFromBot("@whiskeysockets/baileys/package.json").version } catch { /* optional */ }
+  }
+
+  fs.mkdirSync(dir, { recursive: true })
+  const file = path.join(dir, "capture.ndjson")
+  const file1 = path.join(dir, "capture.1.ndjson")
+
+  // salt: keyed hash, so numbers cannot be recovered by hashing the whole phone-number space
+  let salt = opts.salt
+  if (!salt) {
+    const sf = path.join(dir, ".salt")
+    try { salt = fs.readFileSync(sf, "utf8").trim() } catch { /* new dir */ }
+    if (!salt) { salt = crypto.randomBytes(16).toString("hex"); try { fs.writeFileSync(sf, salt, { mode: 0o600 }) } catch { /* memory only */ } }
+  }
+
+  // ---- masking ----
+  function fake(run) {
+    const h = crypto.createHmac("sha256", salt).update(run).digest()
+    let out = ""
+    for (let i = 0; i < run.length; i++) out += String(h[i % h.length] % 10)
+    return out[0] === "0" ? "1" + out.slice(1) : out
+  }
+  const maskJid = s => {
+    if (!mask || typeof s !== "string") return s
+    const m = JID_RE.exec(s)
+    return m ? m[1].replace(/\d{4,}/g, fake) + "@" + m[2] : s
+  }
+  const hashId = s => "<id:" + crypto.createHmac("sha256", salt).update(String(s)).digest("hex").slice(0, 8) + ">"
+
+  // generic sanitizer: keeps SHAPE, drops CONTENT
+  function clean(v, key = "", depth = 0) {
+    if (v == null || typeof v === "boolean" || typeof v === "number") return v
+    if (typeof v === "bigint") return Number(v)
+    if (typeof v === "string") {
+      if (JID_RE.test(v)) return maskJid(v)
+      if (key === "id") return hashId(v)
+      if (KEEP_KEYS.has(key)) return v.slice(0, 40)
+      return `<str:${v.length}>`
+    }
+    if (isBin(v)) return `<bin:${v.length}>`
+    if (depth >= MAX_DEPTH) return "<deep>"
+    if (Array.isArray(v)) {
+      const out = v.slice(0, MAX_ITEMS).map(x => clean(x, key, depth + 1))
+      if (v.length > MAX_ITEMS) out.push(`<+${v.length - MAX_ITEMS} more>`)
+      return out
+    }
+    if (typeof v === "object") {
+      const out = {}
+      for (const k of Object.keys(v)) out[k] = DROP_KEYS.has(k) ? "<dropped>" : clean(v[k], k, depth + 1)
+      return out
+    }
+    return `<${typeof v}>`
+  }
+
+  // a raw binary node ({tag, attrs, content}) without any payload
+  function cleanNode(n, depth = 0) {
+    if (isBin(n)) return `<bin:${n.length}>`
+    if (typeof n === "string") return `<str:${n.length}>`
+    if (!n || typeof n !== "object" || depth >= MAX_DEPTH) return "<deep>"
+    const attrs = {}
+    for (const [k, v] of Object.entries(n.attrs || {})) {
+      if (typeof v === "string" && JID_RE.test(v)) attrs[k] = maskJid(v)
+      else if (k === "id") attrs[k] = hashId(v)
+      else if (KEEP_ATTRS.has(k)) attrs[k] = v
+      else attrs[k] = `<str:${String(v).length}>`
+    }
+    const out = { tag: n.tag, attrs }
+    if (Array.isArray(n.content)) {
+      out.content = n.content.slice(0, MAX_ITEMS).map(c => cleanNode(c, depth + 1))
+      if (n.content.length > MAX_ITEMS) out.content.push(`<+${n.content.length - MAX_ITEMS} more>`)
+    } else if (n.content != null) out.content = cleanNode(n.content, depth + 1)
+    return out
+  }
+
+  // ---- state ----
+  const stats = { events: {}, frames: {}, alerts: {}, errors: 0, lid: { seen: 0, withNumber: 0, withoutNumber: 0 } }
+  const knownPaths = new Map() // "event:name" -> Set(paths)
+  let buf = []
+  let size = 0
+  try { size = fs.statSync(file).size } catch { /* no file yet */ }
+  let timer = null
+
+  const bump = (obj, k) => { obj[k] = (obj[k] || 0) + 1 }
+
+  function flush() {
+    if (!buf.length) return
+    const text = buf.join("")
+    buf = []
+    try {
+      if (size + text.length > maxBytes) { try { fs.renameSync(file, file1) } catch { /* first rotation */ } size = 0 }
+      fs.appendFileSync(file, text)
+      size += text.length
+    } catch { stats.errors++ }
+  }
+  function write(entry) {
+    buf.push(JSON.stringify(entry) + "\n")
+    if (!timer) { timer = setTimeout(() => { timer = null; flush() }, flushMs); timer.unref?.() }
+  }
+  const onExit = () => flush()
+  process.on("exit", onExit)
+
+  function alert(session, code, level, detail) {
+    bump(stats.alerts, code)
+    const a = { code, level, ...detail }
+    write({ t: Date.now(), session, kind: "alert", ...a })
+    if (consoleMode) console.log(`[capture] ${level === "warn" ? "ALERT" : "note "} ${code} session=${session} ${JSON.stringify(detail)}`)
+    return a
+  }
+
+  function paths(v, prefix = "", depth = 0, out = new Set()) {
+    if (v && typeof v === "object" && !isBin(v) && depth < 4) {
+      if (Array.isArray(v)) { if (v.length) paths(v[0], prefix + "[]", depth + 1, out) }
+      else for (const k of Object.keys(v)) { out.add(prefix + "." + k); paths(v[k], prefix + "." + k, depth + 1, out) }
+    }
+    return out
+  }
+  function trackShape(session, scope, name, summary) {
+    const id = scope + ":" + name
+    const now = paths(summary)
+    const known = knownPaths.get(id)
+    if (!known) { knownPaths.set(id, now); return [] } // first sample is the baseline
+    const found = []
+    for (const p of now) if (!known.has(p)) { known.add(p); found.push(alert(session, "new_field", "info", { scope, name, path: p })) }
+    return found
+  }
+
+  // ---- LID checks (the fragile point) ----
+  function checkKey(session, k) {
+    const found = []
+    if (!k || k.fromMe) return found
+    const group = isGroup(k.remoteJid)
+    const who = group ? k.participant : k.remoteJid
+    const alt = group ? k.participantAlt : k.remoteJidAlt
+    if (!isLid(who) || (!group && isSpecial(who))) return found
+    stats.lid.seen++
+    if (alt) stats.lid.withNumber++
+    else {
+      stats.lid.withoutNumber++
+      found.push(alert(session, "lid_without_number", "warn", {
+        where: group ? "participant" : "remoteJid", jid: maskJid(who), field: group ? "participantAlt" : "remoteJidAlt", present: alt !== undefined
+      }))
+    }
+    return found
+  }
+
+  const userPart = j => String(j || "").split("@")[0].split(":")[0]
+  function checkFrame(session, n, ownLid) {
+    const found = []
+    if (n.tag !== "message") return found
+    const a = n.attrs || {}
+    const sender = a.participant || a.from
+    // the account's own LID (messages sent from the phone / another device) never carries a number: not a problem
+    if (ownLid && userPart(sender) === ownLid) return found
+    const mode = a.addressing_mode || (isLid(sender) ? "lid" : "pn")
+    if (mode === "lid" && !(a.participant_pn || a.sender_pn || a.peer_recipient_pn) && !isSpecial(sender)) {
+      found.push(alert(session, "frame_lid_without_number", "warn", { jid: maskJid(sender), addressing_mode: a.addressing_mode ?? null }))
+    }
+    return found
+  }
+
+  // ---- summaries per event ----
+  function summarizeUpsert(data) {
+    const list = Array.isArray(data?.messages) ? data.messages : []
+    return {
+      type: data?.type, count: list.length,
+      messages: list.slice(0, MAX_ITEMS).map(m => ({
+        key: clean(m?.key),
+        messageType: Object.keys(m?.message || {}).find(k => k !== "messageContextInfo" && k !== "senderKeyDistributionMessage") || null,
+        stubType: m?.messageStubType ?? undefined,
+        hasPushName: !!m?.pushName,
+        ts: Number(m?.messageTimestamp) || undefined
+      }))
+    }
+  }
+
+  function onEvent(session, name, data) {
+    try {
+      bump(stats.events, name)
+      const raw = name === "messages.upsert" ? summarizeUpsert(data) : clean(data)
+      const alerts = []
+      if (name === "messages.upsert") for (const m of data?.messages || []) alerts.push(...checkKey(session, m?.key))
+      if (name === "messages.update") for (const u of Array.isArray(data) ? data : []) alerts.push(...checkKey(session, u?.key))
+      alerts.push(...trackShape(session, "event", name, raw))
+      write({ t: Date.now(), session, kind: "event", name, data: raw, alerts: alerts.length ? alerts.map(a => a.code) : undefined })
+      if (consoleMode === true) console.log(`[capture] ${name} session=${session}`, JSON.stringify(raw).slice(0, 300))
+    } catch { stats.errors++ }
+  }
+
+  function onFrame(session, node, sock) {
+    try {
+      if (isBin(node) || !frameTags.includes(node?.tag)) return
+      bump(stats.frames, node.tag)
+      const data = cleanNode(node)
+      const alerts = checkFrame(session, node, userPart(sock?.user?.lid))
+      write({ t: Date.now(), session, kind: "frame", name: node.tag, data, alerts: alerts.length ? alerts.map(a => a.code) : undefined })
+    } catch { stats.errors++ }
+  }
+
+  // ---- hooks ----
+  function attach(sock, { sessionId = "default" } = {}) {
+    const undo = []
+    try {
+      for (const name of events) {
+        const fn = data => onEvent(sessionId, name, data)
+        sock.ev.on(name, fn)
+        undo.push(() => sock.ev.off?.(name, fn))
+      }
+      if (frameTags.length && sock.ws?.on) {
+        const fn = node => onFrame(sessionId, node, sock)
+        sock.ws.on("frame", fn) // every decoded binary node, before Baileys interprets it
+        undo.push(() => sock.ws.off?.("frame", fn))
+      }
+    } catch { stats.errors++ }
+    return () => { for (const f of undo) try { f() } catch { /* socket already gone */ } }
+  }
+  function attachPool(pool) {
+    const detaches = new Map()
+    pool.on("socket", (id, sock) => { detaches.get(id)?.(); detaches.set(id, attach(sock, { sessionId: id })) })
+    return () => { for (const d of detaches.values()) d(); detaches.clear() }
+  }
+
+  // ---- report / fixtures ----
+  function report() {
+    return JSON.parse(JSON.stringify({ baileys: baileysVersion, ...stats }))
+  }
+  function reportText() {
+    const r = report()
+    const l = r.lid
+    const lines = [
+      `Baileys: ${r.baileys ?? "unknown"}`,
+      `Events: ${Object.entries(r.events).map(([k, v]) => `${k}=${v}`).join(", ") || "none"}`,
+      `Raw nodes: ${Object.entries(r.frames).map(([k, v]) => `${k}=${v}`).join(", ") || "none"}`,
+      `LID senders: ${l.seen} (with number: ${l.withNumber}, WITHOUT number: ${l.withoutNumber})`,
+      `Alerts: ${Object.entries(r.alerts).map(([k, v]) => `${k}=${v}`).join(", ") || "none"}`
+    ]
+    if (r.errors) lines.push(`Capture internal errors (swallowed): ${r.errors}`)
+    return lines.join("\n")
+  }
+
+  function readEntries() {
+    flush()
+    const out = []
+    for (const f of [file1, file]) {
+      let text = ""
+      try { text = fs.readFileSync(f, "utf8") } catch { continue }
+      for (const line of text.split("\n")) { if (!line) continue; try { out.push(JSON.parse(line)) } catch { /* cut line at rotation */ } }
+    }
+    return out
+  }
+
+  // One fixture per distinct (kind, name, shape, alerts), at most `perShape` of each: small files, still covers every variant seen.
+  function exportFixtures(outFile, { kinds = ["event", "frame"], perShape = 2 } = {}) {
+    const seen = new Map()
+    const items = []
+    for (const e of readEntries()) {
+      if (!kinds.includes(e.kind)) continue
+      const sig = [e.kind, e.name, [...paths(e.data)].sort().join(","), (e.alerts || []).join("+")].join("|")
+      const n = seen.get(sig) || 0
+      if (n >= perShape) continue
+      seen.set(sig, n + 1)
+      items.push({ kind: e.kind, name: e.name, data: e.data, alerts: e.alerts || [] })
+    }
+    const doc = { version: 1, baileys: baileysVersion, createdAt: new Date().toISOString(), items }
+    fs.mkdirSync(path.dirname(path.resolve(outFile)), { recursive: true })
+    fs.writeFileSync(outFile, JSON.stringify(doc, null, 2))
+    return { file: outFile, items: items.length }
+  }
+
+  function close() { process.off("exit", onExit); if (timer) clearTimeout(timer); timer = null; flush() }
+
+  return { attach, attachPool, report, reportText, exportFixtures, flush, close, files: { file, file1 }, mask: maskJid, clean, cleanNode }
+}
+
+// reads a fixtures file written by exportFixtures
+function loadFixtures(file) {
+  const doc = JSON.parse(fs.readFileSync(file, "utf8"))
+  if (!doc || !Array.isArray(doc.items)) throw new Error("loadFixtures: invalid file")
+  return doc
+}
+
+module.exports = { createCapture, loadFixtures, EVENTS, FRAME_TAGS }

package/packages/capture/package.json

@@ -0,0 +1 @@
+{ "name": "@morpho/capture", "version": "0.1.0", "description": "Capture tool: records what Baileys delivers (events and raw nodes) with masked data, raises alerts on fragile points (LID without number, new fields) and exports fixtures.", "main": "index.js", "license": "MIT" }

package/packages/links/README.md

@@ -0,0 +1,85 @@
+# morpho-socket/links
+
+A relation between **two people**. What it means is yours — couple, friend, parent, rival, teammate, referral. Morpho stores the edge, enforces the limits you declare and answers "who is linked to whom". Built on [`kv`](../kv).
+
+```js
+const { openKV } = require("morpho-socket/kv")
+const { createLinks, otherOf } = require("morpho-socket/links")
+
+const db = openKV("data/bot.sqlite")
+const links = createLinks({
+  db,
+  types: {
+    couple: { symmetric: true,  max: 1 },                 // one at a time
+    friend: { symmetric: true },                          // unlimited
+    parent: { symmetric: false, max: 2, maxIn: 10 },      // directed: a → b ("a is parent of b")
+  },
+})
+
+const room = links.sub(g.clientId, g.chatId)              // isolated per client and group (optional)
+
+const r = room.link("couple", g.user.number, target.number, { since: "today" })
+if (!r.ok) return g.reply(ERRORS[r.reason])               // "limit-reached" → r.who is the person at the limit
+
+room.get("couple", a, b)                                  // symmetric: order doesn't matter
+room.of(g.user.number)                                    // [{ type, other, direction, data, since, link }]
+room.unlink("couple", a, b)
+```
+
+## Symmetric and directed
+
+- **Symmetric** (`couple`, `friend`): one edge per pair, any order. `max` is the limit **per person** over all their links of that type.
+- **Directed** (`parent`, `follows`): `a → b` is not `b → a`; each has its own edge. `max` limits a person's **outgoing** links, `maxIn` their **incoming** ones.
+- `max` can be a function of the person — `max: person => plans.limitFor(person)` — so limits can follow your plans.
+
+## Outcomes
+
+Expected failures are values, never exceptions; you decide what to say and in which language:
+
+| `reason` | when |
+|---|---|
+| `self` | a person with themselves |
+| `unknown-type` | the type isn't in `types` (when `types` is given) |
+| `already-linked` | that pair already has a link of this type (in that direction) |
+| `limit-reached` | `who` is the person who is full |
+| `not-linked` | `unlink` / `update` on something that doesn't exist |
+
+`link`, `unlink` and `update` run in **one transaction**: a refused call writes nothing.
+
+## API
+
+| | |
+|---|---|
+| `createLinks({ db, name = "links", types?, strict?, now? })` | `types` omitted → any type name works (symmetric, unlimited). With `types`, unknown names are refused unless `strict: false` |
+| `link(type, a, b, data?)` | `{ ok, link }` · `{ ok: false, reason, who? }` |
+| `unlink(type, a, b)` | `{ ok, link }` · `{ ok: false, reason }` — directed needs the exact direction |
+| `update(type, a, b, fn)` | `fn(oldData) → newData`, keeps `since` |
+| `get(type, a, b)` · `has(...)` | the link or `null` |
+| `of(person, { type?, direction? })` | everything a person is part of, oldest first. `direction`: `"sym"` `"out"` `"in"` |
+| `between(a, b)` | every link between two people, any type |
+| `all(type)` | every link of a type in this scope, oldest first (all the couples of a group) |
+| `count(person, type, direction?)` | symmetric → all; directed → outgoing unless you say `"in"` |
+| `unlinkAll(person, { type? })` | when someone leaves or is banned; returns how many were removed |
+| `sub(...parts)` | narrower scope, e.g. `sub(clientId, chatId)` |
+| `otherOf(link, person)` | the other side of a link |
+
+A `link` is `{ type, symmetric, a, b, data, since }`. In symmetric links `a`/`b` are in sorted order, so use `otherOf` instead of assuming who is who.
+
+People are plain strings — use `g.user.number`. Ids and types can't contain `/`; invalid ones throw `TypeError`.
+
+## Example: "marriage" in a few lines
+
+```js
+// !marry @x   (with pending for the proposal)
+const key = pending.key(g.chatId, target.number)
+pending.create(key, { from: g.user.number })
+
+// !accept
+const t = pending.take(pending.key(g.chatId, g.user.number))
+if (t.ok) {
+  const r = room.link("couple", t.request.data.from, g.user.number)
+  if (!r.ok) return g.reply(r.reason === "limit-reached" ? "One of you is already taken" : "Couldn't")
+}
+```
+
+The same two modules build a friendship system, a clan roster or a referral tree — only the type names and limits change.

package/packages/links/index.js

@@ -0,0 +1,191 @@
+// @morpho/links
+//
+// A relation between TWO people. What it means is yours: couple, friend, parent, rival, teammate, referral...
+// Morpho only stores the edge, enforces the limits you declare, and answers "who is linked to whom".
+//
+//   const links = createLinks({
+//     db,                                                        // from @morpho/kv: openKV(...)
+//     types: {
+//       couple: { symmetric: true,  max: 1 },                    // one at a time
+//       friend: { symmetric: true },                             // as many as you like
+//       parent: { symmetric: false, max: 2, maxIn: 10 },         // directed: a -> b  (a is parent of b)
+//     },
+//   })
+//   const room = links.sub(clientId, chatId)                     // isolated: per client and group (optional)
+//
+//   room.link("couple", "5511111", "5522222", { nameA: "Ana", nameB: "Bia" })   // { ok: true, link }
+//   room.link("couple", "5511111", "5533333")                    // { ok: false, reason: "limit-reached", who: "5511111" }
+//   room.get("couple", "5522222", "5511111")                     // symmetric: order doesn't matter
+//   room.of("5511111")                                           // [{ type, other, direction, data, since, link }]
+//   room.unlink("couple", "5511111", "5522222")
+//
+// Expected outcomes are values: { ok: false, reason } with one of
+//   "self" | "unknown-type" | "already-linked" | "limit-reached" (+ who) | "not-linked"
+// Wrong usage (an id with "/", an invalid type name) throws TypeError. `link`/`unlink`/`update` run in ONE transaction.
+//
+// People are plain strings (use g.user.number). Directions in `of()`:  "sym" (symmetric), "out" (a -> other), "in" (other -> a).
+
+const TYPE = /^[A-Za-z0-9_.-]+$/
+const DEFAULTS = { symmetric: true, max: Infinity, maxIn: Infinity }
+
+const id = x => {
+  if (typeof x === "number" && Number.isFinite(x)) x = String(x)
+  if (typeof x !== "string" || !x || x.includes("/")) throw new TypeError('links: a person must be a non-empty string without "/" (use g.user.number)')
+  return x
+}
+const typeName = t => { if (typeof t !== "string" || !TYPE.test(t)) throw new TypeError("links: type must match [A-Za-z0-9_.-]+"); return t }
+
+// the other side of a link, from `person`'s point of view
+function otherOf(link, person) { return link.a === person ? link.b : link.a }
+
+function createLinks({ db, name = "links", types, strict, now = Date.now, _scope = [] } = {}) {
+  if (!db || typeof db.collection !== "function" || typeof db.transaction !== "function")
+    throw new TypeError("links: pass { db } from @morpho/kv (openKV(...))")
+  const col = _scope.length ? db.collection(name).sub(..._scope) : db.collection(name)
+  const known = types ? Object.fromEntries(Object.entries(types).map(([k, v]) => [typeName(k), { ...DEFAULTS, ...v }])) : null
+  const isStrict = strict ?? !!known
+
+  const cfg = t => known?.[t] ?? (isStrict ? null : DEFAULTS)
+  const limit = (v, person) => (typeof v === "function" ? v(person) : v)
+
+  // keys
+  const edgeKey = (t, a, b) => `e/${t}/${a}/${b}`
+  const ixKey = (person, t, dir, other) => `i/${person}/${t}/${dir}/${other}`   // dir: s (symmetric) | o (out) | i (in)
+  const canon = (t, c, a, b) => (c.symmetric && a > b ? [b, a] : [a, b])
+  const DIR = { s: "sym", o: "out", i: "in" }
+
+  const toLink = (t, c, rec) => ({ type: t, symmetric: c.symmetric, a: rec.a, b: rec.b, data: rec.data, since: rec.since })
+
+  function readEdge(t, c, a, b) {
+    const [x, y] = canon(t, c, a, b)
+    const rec = col.get(edgeKey(t, x, y))
+    return rec ? toLink(t, c, rec) : null
+  }
+
+  const api = {
+    // data: any JSON. Returns { ok: true, link } | { ok: false, reason, who? }
+    link(type, a, b, data = null) {
+      typeName(type); a = id(a); b = id(b)
+      const c = cfg(type)
+      if (!c) return { ok: false, reason: "unknown-type" }
+      if (a === b) return { ok: false, reason: "self" }
+      return db.transaction(() => {
+        if (readEdge(type, c, a, b)) return { ok: false, reason: "already-linked" }
+        // limits, per person: symmetric -> all their links of that type; directed -> outgoing (max) and incoming (maxIn)
+        const checks = c.symmetric
+          ? [[a, "s", c.max], [b, "s", c.max]]
+          : [[a, "o", c.max], [b, "i", c.maxIn]]
+        for (const [person, dir, lim] of checks) {
+          const n = col.count(`i/${person}/${type}/${dir}/`)
+          if (n >= limit(lim, person)) return { ok: false, reason: "limit-reached", who: person }
+        }
+        const [x, y] = canon(type, c, a, b)
+        const rec = { a: x, b: y, data, since: now() }
+        col.set(edgeKey(type, x, y), rec)
+        if (c.symmetric) { col.set(ixKey(x, type, "s", y), true); col.set(ixKey(y, type, "s", x), true) }
+        else { col.set(ixKey(x, type, "o", y), true); col.set(ixKey(y, type, "i", x), true) }
+        return { ok: true, link: toLink(type, c, rec) }
+      })
+    },
+
+    // symmetric: any order. directed: exactly a -> b
+    unlink(type, a, b) {
+      typeName(type); a = id(a); b = id(b)
+      const c = cfg(type)
+      if (!c) return { ok: false, reason: "unknown-type" }
+      return db.transaction(() => {
+        const link = readEdge(type, c, a, b)
+        if (!link) return { ok: false, reason: "not-linked" }
+        col.delete(edgeKey(type, link.a, link.b))
+        if (c.symmetric) { col.delete(ixKey(link.a, type, "s", link.b)); col.delete(ixKey(link.b, type, "s", link.a)) }
+        else { col.delete(ixKey(link.a, type, "o", link.b)); col.delete(ixKey(link.b, type, "i", link.a)) }
+        return { ok: true, link }
+      })
+    },
+
+    get(type, a, b) {
+      typeName(type); a = id(a); b = id(b)
+      const c = cfg(type)
+      return c ? readEdge(type, c, a, b) : null
+    },
+    has(type, a, b) { return !!api.get(type, a, b) },
+
+    // change the data of an existing link: fn(oldData) -> newData
+    update(type, a, b, fn) {
+      typeName(type); a = id(a); b = id(b)
+      const c = cfg(type)
+      if (!c) return { ok: false, reason: "unknown-type" }
+      return db.transaction(() => {
+        const link = readEdge(type, c, a, b)
+        if (!link) return { ok: false, reason: "not-linked" }
+        const next = fn(link.data)
+        if (next === undefined) throw new TypeError("links.update: return the new data (or null)")
+        const rec = { a: link.a, b: link.b, data: next, since: link.since }
+        col.set(edgeKey(type, link.a, link.b), rec)
+        return { ok: true, link: toLink(type, c, rec) }
+      })
+    },
+
+    // everything `person` is part of. opts: { type, direction: "sym" | "out" | "in" } (default: all). Oldest first.
+    of(person, { type, direction } = {}) {
+      person = id(person)
+      if (type !== undefined) typeName(type)
+      const out = []
+      for (const k of col.keys(`i/${person}/${type ? type + "/" : ""}`)) {
+        const [, , t, d, ...rest] = k.split("/")
+        const other = rest.join("/")
+        const c = cfg(t) ?? DEFAULTS
+        if (direction && DIR[d] !== direction) continue
+        // the index doesn't know the edge's orientation; the edge key does: symmetric is canonical, directed follows `d`
+        const link = d === "i" ? readEdge(t, { ...c, symmetric: false }, other, person) : readEdge(t, { ...c, symmetric: d === "s" }, person, other)
+        if (link) out.push({ type: t, other, direction: DIR[d], data: link.data, since: link.since, link })
+      }
+      return out.sort((x, y) => x.since - y.since)
+    },
+
+    // how many links `person` has of that type (direction as in of(); default: symmetric -> all, directed -> out)
+    count(person, type, direction) {
+      person = id(person); typeName(type)
+      const c = cfg(type) ?? DEFAULTS
+      const d = direction ? { sym: "s", out: "o", in: "i" }[direction] : (c.symmetric ? "s" : "o")
+      if (!d) throw new TypeError('links.count: direction must be "sym", "out" or "in"')
+      return col.count(`i/${person}/${type}/${d}/`)
+    },
+
+    // every link between two people, any type, any direction
+    between(a, b) {
+      a = id(a); b = id(b)
+      return api.of(a).filter(x => x.other === b).map(x => x.link)
+    },
+
+    // every link of a type in this scope, oldest first (e.g. all the couples of a group)
+    all(type) {
+      typeName(type)
+      const c = cfg(type)
+      if (!c) return []
+      return col.values(`e/${type}/`).map(rec => toLink(type, c, rec)).sort((x, y) => x.since - y.since)
+    },
+
+    // remove every link of a person (they left, were banned...). opts: { type }. Returns how many were removed.
+    unlinkAll(person, { type } = {}) {
+      person = id(person)
+      return db.transaction(() => {
+        let n = 0
+        for (const x of api.of(person, { type })) {
+          const r = x.direction === "in" ? api.unlink(x.type, x.other, person) : api.unlink(x.type, person, x.other)
+          if (r.ok) n++
+        }
+        return n
+      })
+    },
+
+    // narrower scope (links.sub(clientId, chatId)): one client or group never sees another's links
+    sub(...parts) {
+      if (!parts.length) throw new TypeError("links.sub: pass at least one part")
+      return createLinks({ db, name, types, strict, now, _scope: [..._scope, ...parts] })
+    },
+  }
+  return api
+}
+
+module.exports = { createLinks, otherOf }

package/packages/links/package.json

@@ -0,0 +1 @@
+{ "name": "@morpho/links", "version": "0.1.0", "description": "Relations between two people (couple, friend, parent, rival, team...): one edge per pair, optional per-person limits, queries both ways. Built on @morpho/kv.", "main": "index.js", "engines": { "node": ">=22.5.0" }, "license": "MIT" }

package/packages/pending/README.md

@@ -0,0 +1,47 @@
+# morpho-socket/pending
+
+Requests that **wait for an answer and expire by themselves**: a challenge, an invite, a trade offer, an "are you sure? yes/no". Morpho doesn't know what the request *means* — it only holds it, lets exactly one caller take it, and forgets it when its time is up.
+
+```js
+const { createPending } = require("morpho-socket/pending")
+
+const pending = createPending({ ttlMs: 2 * 60_000 })                  // in memory
+// const pending = createPending({ store: db.collection("pending") })  // survives restarts (kv)
+
+// the person who is expected to answer is part of the key
+const key = pending.key(g.chatId, target.number)
+
+const r = pending.create(key, { from: g.user.number, kind: "duel" })
+if (!r.ok) return g.reply(`There is already an open request (${Math.ceil(r.request.msLeft / 1000)}s left)`)
+
+// later, in the "accept" command
+const t = pending.take(key, { match: req => req.data.kind === "duel" })
+if (!t.ok) return g.reply("Nothing to accept.")           // t.reason: "not-found" | "mismatch"
+startDuel(t.request.data.from, g.user.number)
+```
+
+## Behavior
+
+- `create` returns `{ ok: false, reason: "already-pending", request }` when one is open, unless you pass `replace: true`. An expired request never blocks a new one.
+- `take` consumes the request once. With `match`, a request that doesn't fit is **left in place** and the answer is `mismatch`.
+- Expiry is checked by Morpho (`request.expiresAt`), so it doesn't depend on the store's clock. Nothing runs in the background; expired entries are dropped when touched.
+- A request is `{ key, data, createdAt, expiresAt, msLeft }`. `data` is anything JSON.
+
+## API
+
+| | |
+|---|---|
+| `createPending({ store?, ttlMs = 2 min, now? })` | no `store` → memory |
+| `key(...parts)` | `"part\|part"` |
+| `create(key, data, { ttl?, replace? })` | `{ ok, request }` · `{ ok: false, reason: "already-pending", request }` |
+| `peek(key)` · `has(key)` | look without consuming |
+| `take(key, { match? })` | `{ ok, request }` · `{ ok: false, reason: "not-found" \| "mismatch" }` |
+| `cancel(key)` | `true` if there was one |
+| `list(keyPrefix?)` · `clear(keyPrefix?)` | open requests, oldest first |
+| `sub(...parts)` | isolated view, e.g. `pending.sub(clientId, chatId)` |
+
+Wrong usage (empty key, `ttl <= 0`, a `/` inside `sub`) throws `TypeError`; expected outcomes never throw.
+
+`store` is duck-typed and must be **synchronous**: `get(key, fallback)`, `set(key, value, { ttl })`, `delete(key)`, `entries(prefix)`. A [`kv`](../kv) collection fits.
+
+Need "tell me when it expires"? That is a job for a scheduler, not for this module.