domma-cms 0.105.2 → 0.107.0

package/admin/js/lib/related.js

@@ -1 +1 @@
-import{apiRequest as w}from"../api.js";import{fmtDate as b,fmtDateTime as y}from"./dates.js";const f=new Map;export function relatedProviders(e){return f.has(e)||f.set(e,w(`/related/providers?kind=${encodeURIComponent(e)}`,{method:"GET"}).then(t=>Array.isArray(t)?t:[]).catch(()=>[])),f.get(e)}export function relatedMenuItems(e,t,i=n=>n.label){return e.flatMap(n=>n.actions||[]).map(n=>({label:i(n),icon:n.icon||"arrow-right",action:()=>{location.hash=n.url.replace(/\{id\}/g,encodeURIComponent(t)).replace(/^#/,"")}}))}export function relatedWhen(e){if(e?.when)return String(e.when);if(!e?.startAt)return"";const t=new Date(e.startAt);return Number.isNaN(t.getTime())?"":e.allDay?b(t.toISOString().slice(0,10)):y(t)}const a=(e,t,i)=>{const n=document.createElement(e);return t&&(n.className=t),i!=null&&(n.textContent=i),n};export async function mountRelated(e,t,i,{onOpen:n,name:v=""}={}){e.hidden=!0;const h=await relatedProviders(t);if(!h.length||!e.isConnected)return;e.hidden=!1,e.replaceChildren(a("p","related-loading","Loading\u2026"));let g;try{g=await w(`/related?kind=${encodeURIComponent(t)}&id=${encodeURIComponent(i)}`,{method:"GET"})}catch{e.replaceChildren(a("p","related-note","Could not be loaded just now."));return}const I=(g?.providers||[]).map(r=>{const d=a("section","related-section"),s=a("div","related-head"),c=a("span");c.dataset.icon=r.icon||"link",c.dataset.iconSize="14",s.append(c,a("strong","",r.label));const p=(h.find(o=>o.id===r.id)?.actions||[])[0];if(p){const o=a("button","btn btn-sm btn-ghost related-add",p.label.replace(/\{name\}/g,v||"them"));o.type="button",o.addEventListener("click",()=>{n?.(),location.hash=p.url.replace(/\{id\}/g,encodeURIComponent(i)).replace(/^#/,"")}),s.append(o)}if(d.append(s),r.error)d.append(a("p","related-note",r.error));else if(!r.items?.length)d.append(a("p","related-note",`No ${r.label.toLowerCase()} yet.`));else{const o=a("ul","related-list");for(const l of r.items){const m=a("li",l.past?"is-past":""),u=a(l.url?"a":"span","related-title",l.title||"Untitled");l.url&&(u.href=l.url,u.addEventListener("click",()=>n?.())),m.append(u);const C=[relatedWhen(l),l.meta].filter(Boolean).join(" \xB7 ");C&&m.append(a("small","related-meta",C)),o.append(m)}d.append(o)}return d});e.replaceChildren(...I),window.I?.scan?.(e)}
+import{apiRequest as f}from"../api.js";import{fmtDate as E,fmtDateTime as I}from"./dates.js";const b=new Map;export function relatedProviders(e){return b.has(e)||b.set(e,f(`/related/providers?kind=${encodeURIComponent(e)}`,{method:"GET"}).then(t=>Array.isArray(t)?t:[]).catch(()=>[])),b.get(e)}export function relatedMenuItems(e,t,a=n=>n.label){return e.flatMap(n=>n.actions||[]).map(n=>({label:a(n),icon:n.icon||"arrow-right",action:()=>{location.hash=n.url.replace(/\{id\}/g,encodeURIComponent(t)).replace(/^#/,"")}}))}export function relatedWhen(e){if(e?.when)return String(e.when);if(!e?.startAt)return"";const t=new Date(e.startAt);return Number.isNaN(t.getTime())?"":e.allDay?E(t.toISOString().slice(0,10)):I(t)}const r=(e,t,a)=>{const n=document.createElement(e);return t&&(n.className=t),a!=null&&(n.textContent=a),n};export function transcriptOf(e){const t=e?.transcript;if(!t||typeof t.url!="string"||!/^\/[\w\-/%.]+$/.test(t.url)||t.url.includes(".."))return null;const a=Math.max(0,Number(t.count)|0);return a?{url:t.url,count:a,title:String(t.title||"Call chat").slice(0,160)}:null}function R(e,t){const a=r("button","btn btn-sm btn-ghost related-chat",`${e.count} message${e.count===1?"":"s"}`);return a.type="button",a.title="Read the chat from this call",a.addEventListener("click",async()=>{a.disabled=!0;try{const[n,d]=await Promise.all([f(e.url,{method:"GET"}),import("/plugins/_lib/admin/ui/transcript.js")]);await d.openTranscript({title:e.title,subtitle:t?`Call started ${t}`:"",items:n?.items||[]})}catch(n){window.E?.toast?.(n?.status===404?"That chat is not available.":"The chat could not be loaded just now.",{type:"warning"})}finally{a.disabled=!1}}),a}export async function mountRelated(e,t,a,{onOpen:n,name:d=""}={}){e.hidden=!0;const g=await relatedProviders(t);if(!g.length||!e.isConnected)return;e.hidden=!1,e.replaceChildren(r("p","related-loading","Loading\u2026"));let w;try{w=await f(`/related?kind=${encodeURIComponent(t)}&id=${encodeURIComponent(a)}`,{method:"GET"})}catch{e.replaceChildren(r("p","related-note","Could not be loaded just now."));return}const v=(w?.providers||[]).map(l=>{const s=r("section","related-section"),p=r("div","related-head"),u=r("span");u.dataset.icon=l.icon||"link",u.dataset.iconSize="14",p.append(u,r("strong","",l.label));const m=(g.find(i=>i.id===l.id)?.actions||[])[0];if(m){const i=r("button","btn btn-sm btn-ghost related-add",m.label.replace(/\{name\}/g,d||"them"));i.type="button",i.addEventListener("click",()=>{n?.(),location.hash=m.url.replace(/\{id\}/g,encodeURIComponent(a)).replace(/^#/,"")}),p.append(i)}if(s.append(p),l.error)s.append(r("p","related-note",l.error));else if(!l.items?.length)s.append(r("p","related-note",`No ${l.label.toLowerCase()} yet.`));else{const i=r("ul","related-list");for(const o of l.items){const c=r("li",o.past?"is-past":""),h=r(o.url?"a":"span","related-title",o.title||"Untitled");o.url&&(h.href=o.url,h.addEventListener("click",()=>n?.())),c.append(h);const C=[relatedWhen(o),o.meta].filter(Boolean).join(" \xB7 ");C&&c.append(r("small","related-meta",C));const y=transcriptOf(o);y&&c.append(R(y,relatedWhen(o))),i.append(c)}s.append(i)}return s});e.replaceChildren(...v),window.I?.scan?.(e)}

package/admin/js/templates/docs/usage-tools.html

@@ -37,6 +37,17 @@
                       screen shows their link to copy or send. They need no account or app, and wait until you let
                       them in. The link works for 3 hours. The contact's <strong>Calls</strong> list shows your
                       recent calls with them.</p>
+                  <p>What is typed in the call's chat is kept with the call. A call on the contact's
+                      <strong>Calls</strong> list shows how many messages it has - click that to read them (only
+                      you, as the one who made the call, or an admin). If you open the call again while it lasts,
+                      the earlier messages are still there.</p>
+                  <p><strong>Add people</strong> while the call is on: as the host, click <strong>Add people</strong>
+                      in the call's control bar, search your contacts and the team, or type a name and email, and
+                      click <strong>Invite</strong>. Each person gets a link of their own - by email, and team
+                      members also as a notification and, when Messages is on, a message from you. They knock and
+                      you let them in. <strong>Copy link</strong> gives you a link to pass on yourself. The same
+                      button is in online bookings' calls (Booking Pro) and online meetings (Calendar); in a
+                      Messages call it rings in another team member.</p>
                   <p>Who may start a call is the <strong>Calls</strong> permission under <strong>System &gt;
                       Roles</strong>; Admin is given it once, the first time a Tool with calls runs. A site without
                       any of those Tools has no instant calls at all.</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "0.105.2",
+  "version": "0.107.0",
   "description": "File-based CMS powered by Domma and Fastify. Run npx domma-cms my-site to create a new project.",
   "type": "module",
   "main": "server/server.js",

package/plugins/_lib/admin/ui/transcript.js

@@ -0,0 +1,154 @@
+/**
+ * A call's chat, read-only, in a slideover - WhatsApp-style bubbles, day
+ * dividers, system lines ("Jo joined") centred. Shared by the CMS's instant
+ * calls (a contact's Calls list), Booking (a booking's panel) and Calendar (an
+ * online event's editor). Import it over HTTP: `/plugins/_lib/admin/ui/transcript.js`.
+ *
+ * Items are the call engine's (`_lib/call/CLAUDE.md` "Chat history"). The rows
+ * are built in JS (`transcriptRows`, pure) and every string reaches the page
+ * through a domma-reactive text binding - chat is never HTML. The stylesheet is
+ * this module's own (`--dm-*` tokens only), added to the page once.
+ *
+ * @module _lib/admin/ui/transcript
+ */
+import {fmtDate} from './dates.js';
+
+const GROUP_MS = 5 * 60000;
+const HUES = 8;
+
+const dayKey = (d) => `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}`;
+
+/** "Today", "Yesterday" or dd/mm/yyyy - in the reader's zone. */
+export function dayLabel(d, now = new Date()) {
+    if (dayKey(d) === dayKey(now)) return 'Today';
+    const y = new Date(now);
+    y.setDate(y.getDate() - 1);
+    if (dayKey(d) === dayKey(y)) return 'Yesterday';
+    return fmtDate(d);
+}
+
+/** A stable colour (1..8) for a sender. */
+export function hueOf(s) {
+    let h = 0;
+    for (const c of String(s || '')) h = (h * 31 + c.charCodeAt(0)) >>> 0;
+    return String((h % HUES) + 1);
+}
+
+/**
+ * The rows for a transcript: one per item (oldest first), with its day divider,
+ * grouping (same sender within 5 minutes, no system line or new day between),
+ * side and time. PURE.
+ *
+ * @param {object[]} items - the engine's chat items
+ * @param {{mine?: (item: object) => boolean, now?: Date}} [opts]
+ * @returns {{id: string, cls: string, hue: string, day: string, sys: boolean, name: string, showName: boolean, text: string, time: string}[]}
+ */
+export function transcriptRows(items, {mine = (i) => i?.mine === true, now = new Date()} = {}) {
+    const rows = [];
+    let last = null;
+    const seen = new Set();
+    for (const raw of Array.isArray(items) ? items : []) {
+        if (!raw || typeof raw.text !== 'string' || !raw.id || seen.has(raw.id)) continue;
+        seen.add(raw.id);
+        const at = new Date(raw.at || 0);
+        const when = Number.isNaN(at.getTime()) ? new Date(0) : at;
+        const sys = raw.kind === 'system';
+        const sender = String(raw.who || raw.from || raw.name || '');
+        const isMine = !sys && mine(raw) === true;
+        const day = !last || dayKey(last.when) !== dayKey(when) ? dayLabel(when, now) : '';
+        const first = sys || Boolean(day) || !last || last.sys || last.sender !== sender || when - last.when > GROUP_MS;
+        rows.push({
+            id: String(raw.id), sys, day, text: raw.text, name: String(raw.name || 'Someone'), showName: first && !sys && !isMine,
+            hue: hueOf(sender),
+            time: when.toLocaleTimeString([], {hour: '2-digit', minute: '2-digit', hourCycle: 'h23'}),
+            cls: ['dmt-msg', sys ? 'is-sys' : isMine ? 'is-mine' : 'is-other', first ? 'is-first' : 'is-cont', day ? 'has-day' : ''].join(' ').trim()
+        });
+        last = {when, sys, sender};
+    }
+    return rows;
+}
+
+/** How many typed messages (not system lines). */
+export const messageCount = (items) => (Array.isArray(items) ? items.filter(i => i?.kind === 'chat').length : 0);
+
+/** "3 messages" / "1 message". */
+export const messagesLabel = (n) => `${n} message${n === 1 ? '' : 's'}`;
+
+const CSS = `
+.dmt-panel { display: flex; flex-direction: column; gap: .5rem; min-height: 100%; }
+.dmt-sub { margin: 0; color: var(--dm-text-muted); font-size: .85rem; }
+.dmt-list { list-style: none; margin: 0; padding: .6rem .7rem 1rem; border-radius: .6rem; background: var(--dm-background-alt, var(--dm-surface)); border: 1px solid var(--dm-border); flex: 1; }
+.dmt-empty { color: var(--dm-text-muted); font-size: .9rem; text-align: center; padding: 1.5rem .5rem; }
+.dmt-msg { display: flex; flex-direction: column; margin-top: 2px; }
+.dmt-msg.is-first { margin-top: .6rem; }
+.dmt-msg.is-mine { align-items: flex-end; }
+.dmt-msg.is-other { align-items: flex-start; }
+.dmt-msg.is-sys { align-items: center; margin-top: .5rem; }
+.dmt-day { align-self: center; margin: .5rem 0 .3rem; }
+.dmt-day span, .dmt-sys span { display: inline-block; padding: .22rem .6rem; border-radius: .45rem; background: var(--dm-surface-raised, var(--dm-surface)); color: var(--dm-text-muted);
+  font-size: .75rem; border: 1px solid var(--dm-border); }
+.dmt-day span { text-transform: uppercase; letter-spacing: .03em; font-size: .68rem; }
+.dmt-bubble { position: relative; max-width: 85%; padding: .36rem .55rem .3rem .6rem; border-radius: .55rem; background: var(--dm-surface-raised, var(--dm-surface));
+  color: var(--dm-text); border: 1px solid var(--dm-border); white-space: pre-wrap; overflow-wrap: anywhere; line-height: 1.35; }
+.is-mine .dmt-bubble { background: var(--dm-success-light, var(--dm-surface-raised)); }
+.is-first.is-mine .dmt-bubble { border-top-right-radius: 0; }
+.is-first.is-other .dmt-bubble { border-top-left-radius: 0; }
+.dmt-from { display: block; font-size: .78rem; font-weight: 600; margin-bottom: .1rem; color: var(--dm-primary); }
+.dmt-time { float: right; position: relative; top: .3rem; margin-left: .6rem; font-size: .68rem; line-height: 1; color: var(--dm-text-muted); font-variant-numeric: tabular-nums; }
+.dmt-msg[data-hue="2"] .dmt-from, .dmt-msg[data-hue="7"] .dmt-from { color: var(--dm-success); }
+.dmt-msg[data-hue="3"] .dmt-from, .dmt-msg[data-hue="8"] .dmt-from { color: var(--dm-info); }
+.dmt-msg[data-hue="4"] .dmt-from { color: var(--dm-danger); }
+.dmt-msg[data-hue="5"] .dmt-from { color: var(--dm-warning); }
+.dmt-panel [hidden] { display: none !important; }
+`;
+
+function addStyles() {
+    if (document.getElementById('dm-transcript-css')) return;
+    const style = document.createElement('style');
+    style.id = 'dm-transcript-css';
+    style.textContent = CSS;
+    document.head.appendChild(style);
+}
+
+const ROW = `<li data-bind-class="cls" data-bind-data-hue="hue">
+  <div class="dmt-day" data-bind-hidden="!day"><span data-bind-text="day"></span></div>
+  <div class="dmt-sys" data-bind-hidden="!sys"><span data-bind-text="text"></span></div>
+  <div class="dmt-bubble" data-bind-hidden="sys"><span class="dmt-from" data-bind-hidden="!showName" data-bind-text="name"></span><span class="dmt-text" data-bind-text="text"></span><span class="dmt-time" data-bind-text="time"></span></div>
+</li>`;
+
+/**
+ * Open the transcript in a right-hand slideover. `title` and `subtitle` are
+ * plain text. Returns the slideover (null when the admin has no Domma).
+ *
+ * @param {{title?: string, subtitle?: string, items: object[], mine?: (item: object) => boolean, empty?: string}} opts
+ */
+export async function openTranscript({title = 'Call chat', subtitle = '', items = [], mine, empty = 'Nothing was typed in the chat.'} = {}) {
+    if (!window.E?.slideover || !window.M?.applyBindings) return null;
+    addStyles();
+    const rows = M.observable(transcriptRows(items, mine ? {mine} : {}));
+    const sub = M.observable(String(subtitle || ''));
+    const emptyText = M.observable(String(empty || ''));
+    // The title goes in as text: Domma's slideover title takes HTML.
+    const so = E.slideover({title: String(title).replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`), size: 'md', position: 'right'});
+    const panel = document.createElement('div');
+    panel.className = 'dmt-panel';
+    panel.innerHTML = `<p class="dmt-sub" data-bind-hidden="!sub.value" data-bind-text="sub.value"></p>
+<p class="dmt-empty" data-bind-hidden="rows.value.length" data-bind-text="emptyText.value"></p>
+<div class="dmt-wrap" data-bind-hidden="!rows.value.length"><ol class="dmt-list" aria-label="Chat from the call" data-each="rows.value key=id"></ol></div>`;
+    // The row template goes in before binding (a templateUrl would eat {{...}}; this has none, but keep the order).
+    panel.querySelector('.dmt-list').innerHTML = ROW;
+    so.element.appendChild(panel);
+    const bindings = M.applyBindings({rows, sub, emptyText}, panel);
+    let onceClosed = null;
+    try { onceClosed = (await import('/admin/js/lib/tool-kit.js')).onceClosed; } catch { /* older admin */ }
+    const dispose = () => { try { bindings?.dispose?.(); } catch { /* gone */ } };
+    if (typeof onceClosed === 'function') onceClosed(so, dispose);
+    else {
+        const close = so.close.bind(so);
+        so.close = (...a) => { const r = close(...a); dispose(); setTimeout(() => { try { so.destroy?.(); } catch { /* gone */ } so.element?.remove(); }, 400); return r; };
+    }
+    so.open();
+    // Newest at the bottom, in view.
+    setTimeout(() => { const list = panel.querySelector('.dmt-list'); list?.lastElementChild?.scrollIntoView?.({block: 'end'}); }, 60);
+    return so;
+}

package/plugins/_lib/call/chatStore.js

@@ -0,0 +1,103 @@
+/**
+ * A call chat store for a Tool: one JSON file holding every room's transcript,
+ * made to be handed to `mountCallRoutes(..., {chat: store})` (its `load` and
+ * `save`), plus what an admin screen needs to show a transcript afterwards.
+ *
+ * File shape: `{rooms: {<room>: {updatedAt, items: [...]}}}`. Growth is capped
+ * twice: the last `maxItems` items per room (the engine's HISTORY_MAX), and the
+ * `maxRooms` most recently used rooms (older transcripts go first). Writes are
+ * one after another (a promise chain) through `_lib/dataStore.js` (atomic
+ * .tmp + rename); the file is read once and then kept in memory - one process.
+ *
+ * @module _lib/call/chatStore
+ */
+
+import {createStore} from '../dataStore.js';
+import {HISTORY_MAX} from './rooms.js';
+
+/** The fields an item keeps; anything else a caller passes is dropped. */
+export function storedItem(raw) {
+    if (!raw || typeof raw !== 'object' || typeof raw.text !== 'string' || !raw.id) return null;
+    const item = {id: String(raw.id).slice(0, 64), seq: Number(raw.seq) || 0, at: String(raw.at || ''),
+        kind: raw.kind === 'system' ? 'system' : 'chat', from: String(raw.from || '').slice(0, 64),
+        who: String(raw.who || '').slice(0, 64), name: String(raw.name || '').slice(0, 60), text: raw.text.slice(0, 1000)};
+    if (raw.event) item.event = String(raw.event).slice(0, 40);
+    return item;
+}
+
+/** How many typed messages (not system lines) a transcript holds. */
+export const chatCount = (items) => (Array.isArray(items) ? items.filter(i => i?.kind === 'chat').length : 0);
+
+/**
+ * @param {string} file - absolute path of the JSON file (a Tool's data/ folder)
+ * @param {{maxItems?: number, maxRooms?: number, now?: () => number}} [opts]
+ */
+export function createChatStore(file, {maxItems = HISTORY_MAX, maxRooms = 1000, now = Date.now} = {}) {
+    const disk = createStore(file);
+    let data = null;              // {rooms: {}} once read
+    let reading = null;           // the ONE first read: two callers never each replace `data`
+    let chain = Promise.resolve();
+
+    function read() {
+        if (data) return Promise.resolve(data);
+        reading ??= Promise.resolve(disk.read()).then((raw) => {
+            data = {rooms: raw && typeof raw.rooms === 'object' && raw.rooms && !Array.isArray(raw.rooms) ? raw.rooms : {}};
+            return data;
+        }).finally(() => { reading = null; });
+        return reading;
+    }
+    /** Run `fn` after every earlier change; a failure is passed on to its caller, never to the next change. */
+    function queue(fn) {
+        const run = chain.then(fn);
+        chain = run.catch(() => {});
+        return run;
+    }
+    const key = (room) => String(room || '').slice(0, 160);
+
+    return {
+        /** The room's items, oldest first ([] when there are none). */
+        async load(room) {
+            await chain;
+            const r = (await read()).rooms[key(room)];
+            return Array.isArray(r?.items) ? r.items.map(i => ({...i})) : [];
+        },
+
+        /** Add one item (the engine's save). Kept: the last maxItems; the maxRooms most recently used rooms. */
+        save(room, item) {
+            const clean = storedItem(item);
+            if (!clean || !key(room)) return Promise.resolve();
+            return queue(async () => {
+                const d = await read();
+                const k = key(room);
+                const r = d.rooms[k] || (d.rooms[k] = {updatedAt: '', items: []});
+                if (!r.items.some(i => i.id === clean.id)) r.items.push(clean);
+                if (r.items.length > maxItems) r.items.splice(0, r.items.length - maxItems);
+                r.updatedAt = new Date(now()).toISOString();
+                const names = Object.keys(d.rooms);
+                if (names.length > maxRooms) {
+                    names.sort((a, b) => String(d.rooms[a].updatedAt).localeCompare(String(d.rooms[b].updatedAt)))
+                        .slice(0, names.length - maxRooms).forEach(n => { delete d.rooms[n]; });
+                }
+                await disk.write(d);
+            });
+        },
+
+        /** The rooms whose name starts with `prefix`: [{room, count, updatedAt}] (count = typed messages). */
+        async rooms(prefix = '') {
+            await chain;
+            const d = await read();
+            return Object.entries(d.rooms).filter(([k]) => k.startsWith(prefix))
+                .map(([k, r]) => ({room: k, count: chatCount(r.items), updatedAt: r.updatedAt}));
+        },
+
+        /** Forget a room's transcript. */
+        remove(room) {
+            return queue(async () => {
+                const d = await read();
+                if (!(key(room) in d.rooms)) return;
+                delete d.rooms[key(room)];
+                await disk.write(d);
+            });
+        }
+    };
+}

package/plugins/_lib/call/invite.js

@@ -0,0 +1,172 @@
+/**
+ * "Add people" to a call that is under way - the pure parts every Tool shares.
+ *
+ * routes.js mounts the two routes (host only, see there) and calls the Tool's
+ * `invite.search(room, q, ctx)` / `invite.send(room, people, ctx)`. What goes out
+ * (the Join email, a notification, a Messages direct message) is core's:
+ * `server/services/callInvites.js`. This file holds what needs no service:
+ * the request's shape, the invite pass, the search's matching, and limits.
+ *
+ * The invite pass: an extra guest link for people added to a call. It never
+ * reuses the host's key or a guest's own token (those carry a name and an
+ * identity - someone invited with the customer's link would take the
+ * customer's place in the call). A pass is `<nonce>.<sig>`, the HMAC of
+ * `room|nonce` under a key the Tool keeps per call (`newInviteKey()`), so the
+ * key itself never leaves the server and each pass is its own identity: two
+ * invitees never replace each other, and one turned away cannot knock again
+ * with the same link. Every invite (and every "Copy link") gets a new pass.
+ *
+ * @module _lib/call/invite
+ */
+
+import {createHmac, randomBytes, timingSafeEqual} from 'node:crypto';
+
+/** People in one invite request. */
+export const MAX_TARGETS = 10;
+/** People one caller may invite in a minute (a "Copy link" counts as one). */
+export const INVITES_PER_MINUTE = 20;
+/** Rows a search answers with. */
+export const SEARCH_MAX = 12;
+export const EMAIL_RE = /^[^\s@<>"]+@[^\s@<>"]+\.[^\s@<>"]+$/;
+const ID_RE = /^[\w-]{1,64}$/;
+const PASS_RE = /^([\w-]{8,24})\.([\w-]{16,64})$/;
+
+/** A new per-call key for invite passes (kept by the Tool, never sent anywhere). */
+export const newInviteKey = () => randomBytes(24).toString('base64url');
+
+const sign = (key, room, nonce) => createHmac('sha256', String(key)).update(`${room}|${nonce}`).digest('base64url').slice(0, 32);
+
+/** A new invite pass for `room` under the call's `key`. */
+export function invitePass(key, room, nonce = randomBytes(9).toString('base64url')) {
+    if (!key) throw new Error('invitePass needs the call\'s invite key');
+    return `${nonce}.${sign(key, String(room), nonce)}`;
+}
+
+/** The pass's nonce when it was made for this room under this key, else null. */
+export function checkInvitePass(key, room, pass) {
+    const m = PASS_RE.exec(String(pass || ''));
+    if (!key || !m) return null;
+    const want = Buffer.from(sign(key, String(room), m[1]));
+    const got = Buffer.from(m[2]);
+    return want.length === got.length && timingSafeEqual(want, got) ? m[1] : null;
+}
+
+/** "jo@example.com" -> "j•••@example.com": enough to tell two Jos apart, not enough to harvest. */
+export function maskEmail(email) {
+    const s = String(email || '').trim();
+    const at = s.lastIndexOf('@');
+    if (at < 1) return '';
+    return `${s[0]}•••${s.slice(at)}`;
+}
+
+const bool = (v) => v === true;
+const text = (v, n) => String(v ?? '').trim().replace(/\s+/g, ' ').slice(0, n);
+/** One line of plain text, at most `n` characters (names in subjects, notices and messages). */
+export const cleanText = (v, n = 120) => text(v, n);
+
+/**
+ * The invite request, checked: `{people: [{kind: 'contact'|'user', id} | {kind: 'email', name, email}], via}` or
+ * `{error}`. Duplicates are dropped. An empty `people` is allowed (the caller wants a link to copy).
+ *
+ * @param {object} body - {people: [{kind, id} | {name, email}], via: {email, notify, message}}
+ */
+export function cleanInviteRequest(body = {}) {
+    const raw = Array.isArray(body?.people) ? body.people : [];
+    if (raw.length > MAX_TARGETS) return {error: `Add at most ${MAX_TARGETS} people at a time.`};
+    const people = [];
+    const seen = new Set();
+    for (const p of raw) {
+        if (!p || typeof p !== 'object') return {error: 'Someone in the list is not a person.'};
+        if (p.kind === 'contact' || p.kind === 'user') {
+            const id = String(p.id ?? '');
+            if (!ID_RE.test(id)) return {error: 'Someone in the list is not a person.'};
+            const k = `${p.kind}:${id}`;
+            if (!seen.has(k)) { seen.add(k); people.push({kind: p.kind, id}); }
+            continue;
+        }
+        const email = text(p.email, 200).toLowerCase();
+        if (!EMAIL_RE.test(email)) return {error: `"${text(p.email, 60) || 'An email'}" does not look like an email address.`};
+        const name = text(p.name, 120) || email.split('@')[0];
+        const k = `email:${email}`;
+        if (!seen.has(k)) { seen.add(k); people.push({kind: 'email', name, email}); }
+    }
+    const via = body?.via && typeof body.via === 'object' ? body.via : {};
+    return {people, via: {email: bool(via.email), notify: bool(via.notify), message: bool(via.message)}};
+}
+
+/**
+ * Match a search against a host's contacts and the team. Contacts' emails are masked (the rows reach a browser
+ * holding only a call link) and matched only WHOLE - a part of an address would let someone rebuild a masked one
+ * letter by letter; names match on any part. Team members show no email at all.
+ *
+ * @param {{q?: string, contacts?: {id, name, email}[], users?: {id, name}[], excludeUserIds?: string[],
+ *   canMessage?: boolean, limit?: number}} opts - `canMessage`: a direct message can reach team members
+ */
+export function matchPeople({q = '', contacts = [], users = [], excludeUserIds = [], canMessage = false, limit = SEARCH_MAX} = {}) {
+    const want = text(q, 100).toLowerCase();
+    const hit = (...vals) => !want || vals.some(v => String(v || '').toLowerCase().includes(want));
+    const skip = new Set(excludeUserIds.map(String));
+    const team = users.filter(u => u && u.id && !skip.has(String(u.id)) && hit(u.name))
+        .map(u => ({kind: 'user', id: String(u.id), name: text(u.name, 120) || 'Team member', canNotify: true, canMessage: canMessage === true}));
+    // Contacts need something typed: an empty search offers the team only.
+    const known = want ? contacts.filter(c => c && c.id && c.email && (hit(c.name) || String(c.email).trim().toLowerCase() === want))
+        .map(c => ({kind: 'contact', id: String(c.id), name: text(c.name, 120) || c.email.split('@')[0], email: maskEmail(c.email),
+            canNotify: false, canMessage: false})) : [];
+    const byName = (a, b) => a.name.localeCompare(b.name);
+    return [...team.sort(byName), ...known.sort(byName)].slice(0, Math.max(1, limit));
+}
+
+/** A Tool's search rows, as the browser may have them. */
+export function cleanPeople(list) {
+    return (Array.isArray(list) ? list : []).slice(0, SEARCH_MAX * 2).filter(p => p && (p.kind === 'contact' || p.kind === 'user') && ID_RE.test(String(p.id)))
+        .map(p => ({kind: p.kind, id: String(p.id), name: text(p.name, 120) || 'Someone', ...(p.email ? {email: text(p.email, 200)} : {}),
+            canNotify: p.canNotify === true, canMessage: p.canMessage === true}));
+}
+
+/** A Tool's send results, as the browser may have them. */
+export function cleanResults(list) {
+    return (Array.isArray(list) ? list : []).slice(0, MAX_TARGETS).map(r => ({name: text(r?.name, 120) || 'Someone',
+        emailed: r?.emailed === true, notified: r?.notified === true, messaged: r?.messaged === true, ...(r?.error ? {error: text(r.error, 200)} : {})}));
+}
+
+/**
+ * Counts per key in a sliding window: `take(key, n)` is true (and counts n) while the key has room left.
+ *
+ * @param {{max?: number, windowMs?: number, now?: () => number}} [opts]
+ */
+export function createLimiter({max = INVITES_PER_MINUTE, windowMs = 60000, now = Date.now} = {}) {
+    const seen = new Map();   // key -> [times]
+    return {
+        take(key, n = 1) {
+            const t = now();
+            const recent = (seen.get(key) || []).filter(x => x > t - windowMs);
+            if (recent.length + n > max) { seen.set(key, recent); return false; }
+            for (let i = 0; i < n; i++) recent.push(t);
+            seen.set(key, recent);
+            if (seen.size > 5000) for (const [k, l] of seen) if (!l.some(x => x > t - windowMs)) seen.delete(k);
+            return true;
+        },
+        reset: () => seen.clear()
+    };
+}
+
+/** The words of a notification / direct message: "Alex is calling you - Join". */
+export const inviteTitle = (hostName) => `${text(hostName, 80) || 'Someone'} is calling you - Join`;
+export const inviteMessage = (hostName, title, link) =>
+    `${text(hostName, 80) || 'Someone'} is inviting you to join a video call${title ? ` (${text(title, 120)})` : ''} now. Join here: ${link}`;
+
+/**
+ * What "Add people" offers in a call, as the join tells the page (`inviteOptions`):
+ *   search   - search the team (and the host's contacts, when `typed`)
+ *   typed    - contacts and "type a name and email"
+ *   copyLink - Copy link (a new pass, nothing sent)
+ * A Tool's resolve() gives `inviteOptions` (any of the three), or the older `inviteExternal: false` (team only).
+ * `external` stays for pages that read it: typed || copyLink.
+ */
+export function inviteOptionsOf(r = {}) {
+    const given = r.inviteOptions && typeof r.inviteOptions === 'object' ? r.inviteOptions : {};
+    const team = r.inviteExternal === false;
+    const flag = (v, dflt) => (typeof v === 'boolean' ? v : dflt);
+    const o = {search: flag(given.search, true), typed: flag(given.typed, !team), copyLink: flag(given.copyLink, !team)};
+    return {...o, external: o.typed || o.copyLink};
+}