domma-cms 1.27.3 → 1.28.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/CLAUDE.md +2 -2
  3. package/admin/js/app.js +4 -4
  4. package/admin/js/lib/chats-arrange.js +2 -0
  5. package/admin/js/lib/launchers-arrange.js +2 -0
  6. package/admin/js/lib/menu-item-help.js +1 -1
  7. package/admin/js/lib/page-image-hosts.js +2 -2
  8. package/admin/js/lib/shortcode-form.js +6 -6
  9. package/admin/js/lib/shortcode-registry.js +1 -1
  10. package/admin/js/templates/chat-knowledge.html +96 -0
  11. package/admin/js/templates/chats.html +146 -0
  12. package/admin/js/templates/docs/usage-chat.html +96 -0
  13. package/admin/js/templates/docs/usage-launchers.html +83 -0
  14. package/admin/js/templates/docs/usage-media.html +14 -0
  15. package/admin/js/templates/docs/usage-navigation.html +3 -0
  16. package/admin/js/templates/docs/usage-shortcodes.html +8 -0
  17. package/admin/js/templates/documentation.html +8 -0
  18. package/admin/js/templates/launchers.html +105 -0
  19. package/admin/js/views/chat-knowledge.js +60 -0
  20. package/admin/js/views/chats.js +53 -0
  21. package/admin/js/views/doc-pages.js +1 -1
  22. package/admin/js/views/index.js +1 -1
  23. package/admin/js/views/launchers.js +230 -0
  24. package/admin/js/views/menu-editor.js +22 -22
  25. package/admin/js/views/page-editor.js +10 -10
  26. package/docs/DommaFeatures.md +30 -0
  27. package/docs/markdown-shortcodes.md +69 -16
  28. package/package.json +1 -1
  29. package/public/css/image-zoom.css +1 -0
  30. package/public/css/launcher-chat.css +1 -0
  31. package/public/css/launchers.css +1 -0
  32. package/public/css/site.css +1 -1
  33. package/public/js/image-zoom.mjs +30 -0
  34. package/public/js/launcher-chat.mjs +47 -0
  35. package/public/js/launcher-settings.mjs +2 -0
  36. package/public/js/launchers.mjs +12 -0
  37. package/public/js/motion-control.mjs +1 -1
  38. package/public/js/site.js +1 -1
  39. package/server/routes/api/chat.js +203 -0
  40. package/server/routes/api/chats.js +235 -0
  41. package/server/routes/api/launchers.js +50 -0
  42. package/server/routes/launcher-public.js +96 -0
  43. package/server/server.js +33 -0
  44. package/server/services/adapterRegistry.js +4 -4
  45. package/server/services/adapters/FileAdapter.js +18 -0
  46. package/server/services/adapters/MongoAdapter.js +14 -0
  47. package/server/services/chat/conversation.js +458 -0
  48. package/server/services/chat/launcher-bridge.js +73 -0
  49. package/server/services/chat/matcher.js +324 -0
  50. package/server/services/chat/settings.js +118 -0
  51. package/server/services/chat/store.js +532 -0
  52. package/server/services/collectionAccess.js +16 -0
  53. package/server/services/docs.js +2 -0
  54. package/server/services/launchers.js +172 -0
  55. package/server/services/markdown.js +175 -4
  56. package/server/services/number-fields-migration.js +4 -0
  57. package/server/services/permissionRegistry.js +12 -0
  58. package/server/services/presetCollections.js +75 -2
  59. package/server/services/renderer.js +86 -18
  60. package/server/services/roles.js +1 -1
  61. package/server/services/tools.js +1 -0
  62. package/server/templates/page.html +4 -2
@@ -0,0 +1,532 @@
1
+ /**
2
+ * Chat storage - the four chat presets (presetCollections.js) read and written
3
+ * through the collections service, so they sit in MongoDB where the site has it
4
+ * and in files otherwise.
5
+ *
6
+ * chat-knowledge what the bot knows
7
+ * chat-sessions one row per visitor chat; the visitor holds a random token,
8
+ * the row only its SHA-256
9
+ * chat-messages one row per message, numbered within its chat (`n`)
10
+ * chat-unanswered questions the bot could not answer, counted
11
+ *
12
+ * Visitors poll every few seconds, so a poll must not read every message there
13
+ * is: each chat's row is kept in memory (refreshed after CACHE_MS) and a poll
14
+ * reads messages only when the chat's `count` says there are new ones. All
15
+ * writes go through here, one chat at a time (withChat), which is also what
16
+ * keeps message numbers in step.
17
+ *
18
+ * Staff presence ("someone is available") is memory only: it is a few seconds
19
+ * of truth, not a record.
20
+ *
21
+ * @module services/chat/store
22
+ */
23
+ import {createHash, randomBytes} from 'node:crypto';
24
+ import {marked} from 'marked';
25
+ import sanitizeHtml from 'sanitize-html';
26
+ import {createEntry, deleteEntry, getEntry, listEntries, updateEntry} from '../collections.js';
27
+ import {getAdapter} from '../adapterRegistry.js';
28
+ import * as cache from '../cache/index.js';
29
+ import {buildIndex, isOn, listOf, normalise} from './matcher.js';
30
+
31
+ export const SLUGS = Object.freeze({
32
+ knowledge: 'chat-knowledge', sessions: 'chat-sessions', messages: 'chat-messages', unanswered: 'chat-unanswered'
33
+ });
34
+
35
+ export const TEXT_MAX = 1000;
36
+ export const MESSAGES_MAX = 300;
37
+ export const QUESTION_MAX = 300;
38
+ export const ANSWER_MAX = 4000;
39
+ export const LINKS_MAX = 5;
40
+ /** A bot answer is stored as its Knowledge entry's id plus this much of the answer (the entry is the answer). */
41
+ export const ANSWER_SNAPSHOT = 200;
42
+ /** Chats held in memory at most (least recently used go first). */
43
+ export const SESSION_CACHE_MAX = 2000;
44
+ /** Tokens looked up and not found are remembered this long, so a guessed token is not a full read each time. */
45
+ const MISS_MS = 60_000;
46
+ const MISS_MAX = 5000;
47
+ /** A visitor's chat can be picked up again for this long after its last message. */
48
+ export const RESUME_MS = 24 * 3_600_000;
49
+ /** ...and for this long once they have left a message for the team. */
50
+ export const RESUME_MESSAGE_MS = 14 * 86_400_000;
51
+ /** Staff count as available for this long after their inbox last checked in. */
52
+ export const PRESENCE_MS = 75_000;
53
+ const CACHE_MS = 20_000;
54
+
55
+ const now = () => new Date().toISOString();
56
+
57
+ // ---------------------------------------------------------------------------
58
+ // Text
59
+ // ---------------------------------------------------------------------------
60
+
61
+ /** Plain text from a visitor or staff: control characters out, at most two blank lines, capped. */
62
+ export function cleanText(value, max = TEXT_MAX) {
63
+ return String(value ?? '')
64
+ .replace(/\r\n?/g, '\n')
65
+ // eslint-disable-next-line no-control-regex
66
+ .replace(/[\u0000-\u0008\u000b-\u001f\u007f​-‏‪-‮⁦-⁩]/g, '')
67
+ .replace(/\n{3,}/g, '\n\n')
68
+ .trim()
69
+ .slice(0, max);
70
+ }
71
+
72
+ /** A link a Knowledge entry may offer: http(s), mailto:, tel:, or a path on this site. */
73
+ export function safeUrl(value) {
74
+ const s = String(value ?? '').trim();
75
+ if (!s || s.length > 500 || /\s/.test(s)) return null;
76
+ if (/^https?:\/\/[^/\s]+/i.test(s)) return s;
77
+ if (/^(?:mailto|tel):[^\s]+$/i.test(s)) return s;
78
+ if (/^\/(?!\/)/.test(s) && !s.includes('\\')) return s;
79
+ return null;
80
+ }
81
+
82
+ /** An entry's links, cleaned: [{label, url}], at most LINKS_MAX. */
83
+ export function cleanLinks(value) {
84
+ let list = value;
85
+ if (typeof list === 'string') { try { list = JSON.parse(list); } catch { list = []; } }
86
+ if (!Array.isArray(list)) return [];
87
+ return list.map(l => ({label: cleanText(l?.label, 60).replace(/\n/g, ' '), url: safeUrl(l?.url)}))
88
+ .filter(l => l.url).map(l => ({label: l.label || l.url, url: l.url})).slice(0, LINKS_MAX);
89
+ }
90
+
91
+ /**
92
+ * An answer's Markdown as HTML a visitor's browser may show: paragraphs, lists,
93
+ * emphasis, code and links, nothing else. Links that leave the site open in a
94
+ * new tab.
95
+ */
96
+ export function renderAnswer(markdown) {
97
+ const html = marked.parse(String(markdown ?? '').slice(0, ANSWER_MAX), {gfm: true, breaks: true, async: false});
98
+ return sanitizeHtml(html, {
99
+ allowedTags: ['p', 'br', 'strong', 'em', 'b', 'i', 'ul', 'ol', 'li', 'a', 'code'],
100
+ allowedAttributes: {a: ['href', 'target', 'rel']},
101
+ allowedSchemes: ['http', 'https', 'mailto', 'tel'],
102
+ allowProtocolRelative: false,
103
+ transformTags: {
104
+ a: (tag, attribs) => {
105
+ const href = safeUrl(attribs.href);
106
+ if (!href) return {tagName: 'a', attribs: {}};
107
+ const away = /^https?:/i.test(href);
108
+ return {tagName: 'a', attribs: away ? {href, target: '_blank', rel: 'noopener noreferrer'} : {href}};
109
+ }
110
+ }
111
+ }).trim();
112
+ }
113
+
114
+ /** A row's stored value as a number. */
115
+ const int = (v) => (Number.isFinite(Number(v)) ? Math.trunc(Number(v)) : 0);
116
+
117
+ // ---------------------------------------------------------------------------
118
+ // Knowledge
119
+ // ---------------------------------------------------------------------------
120
+
121
+ let knowledgeCache = null;
122
+
123
+ /** Knowledge rows in the shape the admin and the bot use. */
124
+ export function toKnowledge(entry) {
125
+ const d = entry?.data || {};
126
+ return {
127
+ id: entry.id,
128
+ question: String(d.question || ''),
129
+ alternatives: listOf(d.alternatives).join('\n'),
130
+ keywords: listOf(d.keywords, /[\n,]/).join(', '),
131
+ answer: String(d.answer || ''),
132
+ links: cleanLinks(d.links),
133
+ enabled: isOn(d.enabled),
134
+ hits: int(d.hits),
135
+ lastUsedAt: d.lastUsedAt || null,
136
+ sample: d.sample === true || d.sample === 'true',
137
+ updatedAt: entry?.meta?.updatedAt || null
138
+ };
139
+ }
140
+
141
+ export async function listKnowledge() {
142
+ const {entries} = await listEntries(SLUGS.knowledge, {limit: 0, sort: 'question', order: 'asc'});
143
+ return entries.map(toKnowledge);
144
+ }
145
+
146
+ /** The bot's index, rebuilt after any change (and at most every CACHE_MS otherwise). */
147
+ export async function knowledgeIndex() {
148
+ if (knowledgeCache && Date.now() - knowledgeCache.at < CACHE_MS) return knowledgeCache;
149
+ const list = await listKnowledge();
150
+ knowledgeCache = {at: Date.now(), byId: new Map(list.map(k => [k.id, k])), index: buildIndex(list)};
151
+ return knowledgeCache;
152
+ }
153
+
154
+ export function invalidateKnowledge() { knowledgeCache = null; }
155
+
156
+ /**
157
+ * Validate and shape a Knowledge entry from the admin.
158
+ *
159
+ * @returns {{data?: object, error?: string}}
160
+ */
161
+ export function knowledgeInput(body = {}) {
162
+ const question = cleanText(body.question, QUESTION_MAX).replace(/\n/g, ' ');
163
+ const answer = cleanText(body.answer, ANSWER_MAX);
164
+ if (!question) return {error: 'A question is needed.'};
165
+ if (!answer) return {error: 'An answer is needed.'};
166
+ const alternatives = listOf(cleanText(body.alternatives, 4000)).map(a => a.slice(0, QUESTION_MAX)).slice(0, 30).join('\n');
167
+ const keywords = listOf(cleanText(body.keywords, 500), /[\n,]/).slice(0, 30).join(', ');
168
+ return {data: {question, alternatives, keywords, answer, links: cleanLinks(body.links), enabled: body.enabled !== false}};
169
+ }
170
+
171
+ export async function createKnowledge(body, userId = null) {
172
+ const {data, error} = knowledgeInput(body);
173
+ if (error) return {error};
174
+ const entry = await createEntry(SLUGS.knowledge, {...data, hits: 0, sample: false}, {createdBy: userId, source: 'admin'});
175
+ invalidateKnowledge();
176
+ return {item: toKnowledge(entry)};
177
+ }
178
+
179
+ export async function updateKnowledge(id, body) {
180
+ const existing = await getEntry(SLUGS.knowledge, id);
181
+ if (!existing) return {missing: true};
182
+ const {data, error} = knowledgeInput({...toKnowledge(existing), ...body});
183
+ if (error) return {error};
184
+ const entry = await updateEntry(SLUGS.knowledge, id, {...existing.data, ...data, sample: false});
185
+ invalidateKnowledge();
186
+ return {item: toKnowledge(entry)};
187
+ }
188
+
189
+ export async function removeKnowledge(id) {
190
+ if (!await getEntry(SLUGS.knowledge, id)) return false;
191
+ await deleteEntry(SLUGS.knowledge, id);
192
+ invalidateKnowledge();
193
+ return true;
194
+ }
195
+
196
+ /** Count an answer given. Never throws: a counter must not break a reply. */
197
+ export async function countHit(id) {
198
+ try {
199
+ const existing = await getEntry(SLUGS.knowledge, id);
200
+ if (!existing) return;
201
+ await updateEntry(SLUGS.knowledge, id, {...existing.data, hits: int(existing.data.hits) + 1, lastUsedAt: now()});
202
+ const cached = knowledgeCache?.byId.get(id);
203
+ if (cached) cached.hits += 1;
204
+ } catch { /* counting is a nicety */ }
205
+ }
206
+
207
+ /** Starter entries, clearly marked as examples, put in once on a site's first start with chat. */
208
+ export const EXAMPLE_KNOWLEDGE = Object.freeze([
209
+ {question: 'What are your opening hours?', alternatives: 'When are you open?\nWhat time do you close?\nAre you open at the weekend?',
210
+ keywords: 'hours, open, closed', answer: '**Example answer - change it in Chats > Knowledge.**\n\nWe are open Monday to Friday, 9am to 5pm.'},
211
+ {question: 'How do I contact you?', alternatives: 'What is your phone number?\nWhat is your email address?\nHow can I get in touch?',
212
+ keywords: 'contact, phone, email', answer: '**Example answer - change it in Chats > Knowledge.**\n\nEmail us or call during opening hours - our details are on the contact page.',
213
+ links: [{label: 'Contact us', url: '/contact'}]},
214
+ {question: 'Where are you?', alternatives: 'What is your address?\nHow do I find you?\nIs there parking?',
215
+ keywords: 'address, location, directions, parking', answer: '**Example answer - change it in Chats > Knowledge.**\n\nPut your address and how to get here in this answer.'},
216
+ {question: 'How much does it cost?', alternatives: 'What are your prices?\nDo you have a price list?',
217
+ keywords: 'price, cost', answer: '**Example answer - change it in Chats > Knowledge.**\n\nPrices depend on what you need - ask to talk to a person and we will tell you.'}
218
+ ]);
219
+
220
+ /**
221
+ * Put the example entries in when the Knowledge is empty and examples were never
222
+ * offered before. `marker` says whether they were; seeding is once per site.
223
+ *
224
+ * @param {{seeded: () => boolean, markSeeded: () => void}} marker
225
+ * @returns {Promise<number>} entries added
226
+ */
227
+ export async function seedExampleKnowledge(marker) {
228
+ if (marker.seeded()) return 0;
229
+ const {total} = await listEntries(SLUGS.knowledge, {limit: 1});
230
+ let added = 0;
231
+ if (!total) {
232
+ for (const ex of EXAMPLE_KNOWLEDGE) {
233
+ await createEntry(SLUGS.knowledge, {...ex, links: ex.links || [], enabled: true, hits: 0, sample: true}, {source: 'seed'});
234
+ added++;
235
+ }
236
+ invalidateKnowledge();
237
+ }
238
+ marker.markSeeded();
239
+ return added;
240
+ }
241
+
242
+ /** Take out every example entry nobody has changed. */
243
+ export async function removeExampleKnowledge() {
244
+ const list = await listKnowledge();
245
+ let removed = 0;
246
+ for (const k of list.filter(k => k.sample)) { await deleteEntry(SLUGS.knowledge, k.id); removed++; }
247
+ invalidateKnowledge();
248
+ return removed;
249
+ }
250
+
251
+ // ---------------------------------------------------------------------------
252
+ // Unanswered
253
+ // ---------------------------------------------------------------------------
254
+
255
+ export function toUnanswered(entry) {
256
+ const d = entry?.data || {};
257
+ return {id: entry.id, text: String(d.text || ''), count: int(d.count) || 1, best: d.best || '',
258
+ firstAt: d.firstAt || entry?.meta?.createdAt || null, lastAt: d.lastAt || null, done: d.done === true || d.done === 'true'};
259
+ }
260
+
261
+ /** The Unanswered list stops growing here (visitors can type anything): repeats still count up. */
262
+ export const UNANSWERED_MAX = 1000;
263
+
264
+ /** Note a question the bot could not answer; the same question again counts up. Never throws. */
265
+ export async function logUnanswered(text, best = '') {
266
+ try {
267
+ const clean = cleanText(text, QUESTION_MAX).replace(/\n/g, ' ');
268
+ // Prefixed so an all-digit question stays a string in a MongoDB filter ("2024" would match the number).
269
+ const words = normalise(clean).slice(0, 200);
270
+ if (!words) return;
271
+ const key = `q:${words}`;
272
+ const {entries, total} = await listEntries(SLUGS.unanswered, {limit: 1, filter: {key}});
273
+ const at = now();
274
+ const existing = entries[0];
275
+ if (existing) {
276
+ await updateEntry(SLUGS.unanswered, existing.id, {...existing.data, count: int(existing.data.count) + 1, lastAt: at, done: false, best: best || existing.data.best || ''});
277
+ } else {
278
+ if (total === 0 && (await listEntries(SLUGS.unanswered, {limit: 1})).total >= UNANSWERED_MAX) return;
279
+ await createEntry(SLUGS.unanswered, {text: clean, key, count: 1, best: best || '', firstAt: at, lastAt: at, done: false}, {source: 'chat'});
280
+ }
281
+ } catch { /* the log is a nicety */ }
282
+ }
283
+
284
+ export async function listUnanswered({includeDone = false} = {}) {
285
+ const {entries} = await listEntries(SLUGS.unanswered, {limit: 0, sort: 'lastAt', order: 'desc'});
286
+ return entries.map(toUnanswered).filter(u => includeDone || !u.done);
287
+ }
288
+
289
+ export async function setUnansweredDone(id, done = true) {
290
+ const existing = await getEntry(SLUGS.unanswered, id);
291
+ if (!existing) return null;
292
+ return toUnanswered(await updateEntry(SLUGS.unanswered, id, {...existing.data, done: !!done}));
293
+ }
294
+
295
+ export async function removeUnanswered(id) {
296
+ if (!await getEntry(SLUGS.unanswered, id)) return false;
297
+ await deleteEntry(SLUGS.unanswered, id);
298
+ return true;
299
+ }
300
+
301
+ // ---------------------------------------------------------------------------
302
+ // Sessions and messages
303
+ // ---------------------------------------------------------------------------
304
+
305
+ /** id -> {entry, at} */
306
+ const sessions = new Map();
307
+ /** tokenHash -> id */
308
+ const byToken = new Map();
309
+ /** id -> Promise: one change at a time per chat. */
310
+ const queues = new Map();
311
+
312
+ export const hashToken = (token) => createHash('sha256').update(String(token)).digest('hex');
313
+ export const newToken = () => randomBytes(32).toString('base64url');
314
+ /** What a token looks like - anything else is not looked up. */
315
+ export const TOKEN_RE = /^[A-Za-z0-9_-]{43}$/;
316
+
317
+ /** tokenHash -> when it was found missing */
318
+ const missing = new Map();
319
+
320
+ function remember(entry) {
321
+ if (!entry) return entry;
322
+ // Re-inserted at the end: Map order is the least-recently-used order.
323
+ sessions.delete(entry.id);
324
+ sessions.set(entry.id, {entry, at: Date.now()});
325
+ if (entry.data?.tokenHash) { byToken.set(entry.data.tokenHash, entry.id); missing.delete(entry.data.tokenHash); }
326
+ while (sessions.size > SESSION_CACHE_MAX) forget(sessions.keys().next().value);
327
+ return entry;
328
+ }
329
+
330
+ /** Take a chat out of memory (it ended, or was deleted). */
331
+ export function forgetSession(id) { forget(id); }
332
+
333
+ /** How many chats and tokens are held in memory (tests). */
334
+ export function _cacheSizes() { return {sessions: sessions.size, byToken: byToken.size, missing: missing.size}; }
335
+
336
+ function forget(id) {
337
+ const held = sessions.get(id);
338
+ if (held?.entry?.data?.tokenHash) byToken.delete(held.entry.data.tokenHash);
339
+ sessions.delete(id);
340
+ }
341
+
342
+ /** Tests: drop every cache. */
343
+ export function _resetCaches() {
344
+ sessions.clear(); byToken.clear(); missing.clear(); queues.clear(); presence.clear(); knowledgeCache = null;
345
+ }
346
+
347
+ /** Run fn for one chat after any change already running for it. */
348
+ export function withChat(id, fn) {
349
+ const prev = queues.get(id) || Promise.resolve();
350
+ const run = prev.catch(() => {}).then(fn);
351
+ const tail = run.catch(() => {}).finally(() => { if (queues.get(id) === tail) queues.delete(id); });
352
+ queues.set(id, tail);
353
+ return run;
354
+ }
355
+
356
+ export async function getSession(id, {fresh = false} = {}) {
357
+ if (typeof id !== 'string' || !id) return null;
358
+ const held = sessions.get(id);
359
+ if (held && !fresh && Date.now() - held.at < CACHE_MS) return held.entry;
360
+ const entry = await getEntry(SLUGS.sessions, id);
361
+ if (!entry) { forget(id); return null; }
362
+ return remember(entry);
363
+ }
364
+
365
+ /**
366
+ * The chat a visitor's token opens, while it may still be picked up - or, with
367
+ * includeClosed, also a recently ended one (so the visitor sees that it ended).
368
+ *
369
+ * @param {string} token
370
+ * @param {{includeClosed?: boolean}} [opts]
371
+ * @returns {Promise<object|null>} the session entry
372
+ */
373
+ export async function sessionByToken(token, {includeClosed = false} = {}) {
374
+ if (typeof token !== 'string' || !TOKEN_RE.test(token)) return null;
375
+ const hash = hashToken(token);
376
+ let id = byToken.get(hash);
377
+ let entry = id ? await getSession(id) : null;
378
+ if (!entry || entry.data.tokenHash !== hash) {
379
+ const seen = missing.get(hash);
380
+ if (seen && Date.now() - seen < MISS_MS) return null;
381
+ const {entries} = await listEntries(SLUGS.sessions, {limit: 1, filter: {tokenHash: hash}});
382
+ entry = entries[0] ? remember(entries[0]) : null;
383
+ id = entry?.id;
384
+ if (!entry) {
385
+ missing.delete(hash);
386
+ missing.set(hash, Date.now());
387
+ while (missing.size > MISS_MAX) missing.delete(missing.keys().next().value);
388
+ }
389
+ }
390
+ if (!entry) return null;
391
+ if (includeClosed && entry.data.status === 'closed') return resumable({...entry.data, status: 'bot'}) ? entry : null;
392
+ return resumable(entry.data) ? entry : null;
393
+ }
394
+
395
+ /** Whether a visitor may still carry on in this chat. */
396
+ export function resumable(data, at = Date.now()) {
397
+ if (!data || data.status === 'closed') return false;
398
+ const last = Date.parse(data.lastAt || '') || 0;
399
+ return at - last < (data.status === 'message' ? RESUME_MESSAGE_MS : RESUME_MS);
400
+ }
401
+
402
+ /** Open a new chat; returns {entry, token}. */
403
+ export async function createSession({launcherId, page = ''}) {
404
+ const token = newToken();
405
+ const at = now();
406
+ const entry = await createEntry(SLUGS.sessions, {
407
+ tokenHash: hashToken(token), launcherId: String(launcherId || '').slice(0, 64),
408
+ status: 'bot', visitorName: '', visitorEmail: '', page: cleanPage(page), summary: '',
409
+ count: 0, unread: 0, misses: 0, askDetails: false, assignedTo: '', assignedName: '',
410
+ lastAt: at, waitingSince: null, closedAt: null
411
+ }, {source: 'chat'});
412
+ return {entry: remember(entry), token};
413
+ }
414
+
415
+ /** The page a chat started on: a path on this site, or nothing. */
416
+ export function cleanPage(value) {
417
+ const s = String(value ?? '').trim().slice(0, 200);
418
+ return /^\/(?!\/)[^\s\\]*$/.test(s) ? s : '';
419
+ }
420
+
421
+ /** Change a chat's row. Call inside withChat. */
422
+ export async function patchSession(id, patch) {
423
+ const entry = await getSession(id, {fresh: true});
424
+ if (!entry) return null;
425
+ const updated = await updateEntry(SLUGS.sessions, id, {...entry.data, ...patch});
426
+ return remember(updated);
427
+ }
428
+
429
+ /**
430
+ * Add a message to a chat and move its counters. Call inside withChat.
431
+ *
432
+ * @param {string} id
433
+ * @param {{from: string, text?: string, answerId?: string, suggestions?: Array, staffName?: string}} msg
434
+ * @param {object} [patch] - more changes to the chat's row
435
+ * @returns {Promise<{session: object, message: object}|null>}
436
+ */
437
+ export async function addMessage(id, msg, patch = {}) {
438
+ const session = await getSession(id, {fresh: true});
439
+ if (!session) return null;
440
+ const n = int(session.data.count) + 1;
441
+ const message = await createEntry(SLUGS.messages, {
442
+ sessionId: id, n, from: msg.from, text: cleanText(msg.text, msg.answerId ? ANSWER_SNAPSHOT : TEXT_MAX),
443
+ answerId: msg.answerId || '', suggestions: Array.isArray(msg.suggestions) ? msg.suggestions : [],
444
+ staffName: msg.staffName || ''
445
+ }, {source: 'chat'});
446
+ const at = message.meta.createdAt;
447
+ const data = {...session.data, ...patch, count: n, lastAt: at};
448
+ if (msg.from === 'visitor' && !data.summary) data.summary = cleanText(msg.text, 140).replace(/\n/g, ' ');
449
+ const updated = remember(await updateEntry(SLUGS.sessions, id, data));
450
+ return {session: updated, message};
451
+ }
452
+
453
+ /** A chat's messages after number `after`, oldest first. */
454
+ export async function messagesAfter(id, after = 0) {
455
+ const session = await getSession(id);
456
+ if (!session || int(session.data.count) <= after) return [];
457
+ const {entries} = await listEntries(SLUGS.messages, {limit: 0, sort: 'n', order: 'asc', filter: {sessionId: id, n_gt: String(after)}});
458
+ return entries.filter(m => int(m.data.n) > after).sort((a, b) => int(a.data.n) - int(b.data.n));
459
+ }
460
+
461
+ export async function listSessions({statuses = null} = {}) {
462
+ const filter = Array.isArray(statuses) && statuses.length ? {status_in: statuses.join(',')} : undefined;
463
+ const {entries} = await listEntries(SLUGS.sessions, {limit: 0, sort: 'lastAt', order: 'desc', ...(filter && {filter})});
464
+ for (const e of entries) remember(e);
465
+ return entries;
466
+ }
467
+
468
+ /** Delete entries by id in one write where the store can (both adapters can), else one by one. */
469
+ export async function removeEntries(slug, ids) {
470
+ if (!ids.length) return 0;
471
+ const adapter = await getAdapter(slug);
472
+ let n = 0;
473
+ if (typeof adapter.removeMany === 'function') n = await adapter.removeMany(slug, ids);
474
+ else for (const id of ids) { try { await adapter.remove(slug, id); n++; } catch { /* already gone */ } }
475
+ await cache.invalidateTags([`collection:${slug}`]);
476
+ return n;
477
+ }
478
+
479
+ /** Delete a chat and its messages. */
480
+ export async function removeSession(id) {
481
+ const entry = await getEntry(SLUGS.sessions, id);
482
+ if (!entry) return false;
483
+ const {entries} = await listEntries(SLUGS.messages, {limit: 0, filter: {sessionId: id}});
484
+ await removeEntries(SLUGS.messages, entries.map(m => m.id));
485
+ await deleteEntry(SLUGS.sessions, id);
486
+ forget(id);
487
+ return true;
488
+ }
489
+
490
+ /**
491
+ * Delete several chats and every message of theirs - and any message whose chat
492
+ * is already gone - with one write per collection.
493
+ *
494
+ * @param {string[]} ids - chats to delete
495
+ * @returns {Promise<{chats: number, messages: number}>}
496
+ */
497
+ export async function removeSessionsAndOrphans(ids) {
498
+ const doomed = new Set(ids);
499
+ // Messages first: a chat is always written before its first message, so every chat
500
+ // behind a message listed here is in the list of chats read after it.
501
+ const {entries: msgs} = await listEntries(SLUGS.messages, {limit: 0});
502
+ const {entries: rows} = await listEntries(SLUGS.sessions, {limit: 0});
503
+ const live = new Set(rows.map(r => r.id).filter(id => !doomed.has(id)));
504
+ const messages = await removeEntries(SLUGS.messages, msgs.filter(m => !live.has(m.data?.sessionId)).map(m => m.id));
505
+ const chats = await removeEntries(SLUGS.sessions, [...doomed]);
506
+ for (const id of doomed) forget(id);
507
+ return {chats, messages};
508
+ }
509
+
510
+ // ---------------------------------------------------------------------------
511
+ // Staff presence
512
+ // ---------------------------------------------------------------------------
513
+
514
+ /** userId -> {name, seen, available} */
515
+ const presence = new Map();
516
+
517
+ export function checkIn(userId, {name = '', available = true} = {}) {
518
+ if (!userId) return;
519
+ presence.set(String(userId), {name: String(name || '').slice(0, 80), seen: Date.now(), available: available !== false});
520
+ }
521
+
522
+ export function checkOut(userId) { presence.delete(String(userId)); }
523
+
524
+ /** The staff who could answer now. */
525
+ export function staffAvailable(at = Date.now()) {
526
+ return [...presence.entries()].filter(([, p]) => p.available && at - p.seen < PRESENCE_MS).map(([id, p]) => ({id, name: p.name}));
527
+ }
528
+
529
+ export function presenceOf(userId) {
530
+ const p = presence.get(String(userId));
531
+ return p ? {available: p.available, seen: p.seen} : null;
532
+ }
@@ -45,6 +45,18 @@ const OWNER_FIELD = Object.freeze({
45
45
  'contacts-groups': {in: 'meta', field: 'createdBy'}
46
46
  });
47
47
 
48
+ /**
49
+ * Built-in Tools' collections that hold visitors' data (the chat presets): the
50
+ * generic API, views, forms and endpoints need [resource, action] for them, as
51
+ * a plugin's collection needs the plugin's permission. [resource, action, Tool].
52
+ */
53
+ const CORE_TOOL_COLLECTIONS = Object.freeze({
54
+ 'chat-knowledge': ['chats', 'manage', 'Chats'],
55
+ 'chat-sessions': ['chats', 'manage', 'Chats'],
56
+ 'chat-messages': ['chats', 'manage', 'Chats'],
57
+ 'chat-unanswered': ['chats', 'manage', 'Chats']
58
+ });
59
+
48
60
  /** A row anyone with the Tool may read, whoever made it (ownership gates writes only). */
49
61
  const SHARED_READ = new Set(['contacts-groups']);
50
62
 
@@ -165,6 +177,10 @@ export function pluginCollectionGates(plugin, registry = getEffectiveRegistry(),
165
177
  * @returns {string|null}
166
178
  */
167
179
  export function pluginDenial(schema, user, registry, onDisk) {
180
+ const toolGate = CORE_TOOL_COLLECTIONS[schema?.slug];
181
+ if (toolGate && !isRoot(user)) {
182
+ return holds(user, ...toolGate) ? null : `This collection belongs to ${toolGate[2]} - it needs ${toolGate[0]}.${toolGate[1]}`;
183
+ }
168
184
  const plugin = schema?.plugin;
169
185
  if (!plugin || isRoot(user)) return null;
170
186
  const gates = pluginCollectionGates(plugin, registry, onDisk);
@@ -63,6 +63,8 @@ const MAP = [
63
63
  ['usage-tools', 'usage/tools', 'Built-in Tools'],
64
64
  ['usage-dashboard', 'usage/dashboard', 'Dashboard'],
65
65
  ['usage-search-engines', 'usage/search-engines', 'Search Engines & AI'],
66
+ ['usage-launchers', 'usage/launchers', 'Launchers'],
67
+ ['usage-chat', 'usage/chat', 'Chat & Knowledge'],
66
68
  ['tutorial-crud', 'tutorials/crud', 'Building a CRUD App'],
67
69
  ['tutorial-editor', 'tutorials/editor', 'The Editor'],
68
70
  ['tutorial-plugin', 'tutorials/plugin', 'Writing a Tool'],