domma-cms 0.102.1 → 0.104.0

package/plugins/booking/tests/pure.test.js

@@ -0,0 +1,189 @@
+/**
+ * Booking's pure core: wall-clock time in a zone, and which slots are free.
+ * Double booking is the one bug this Tool cannot have, so the slot rules are
+ * pinned down here in detail.
+ */
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {addDays, atWallClock, cleanZone, fromMinutes, isDate, toMinutes, wallClock, weekdayOf} from '../public/lib/time.js';
+import {bookingRange, isFree, pickBookable, slotsFor, spanOf, windowsOn} from '../public/lib/slots.js';
+
+const LDN = 'Europe/London';
+
+test('wall clock <-> instant in London, both sides of the clock changes', () => {
+    assert.equal(atWallClock('2031-01-15', '09:00', LDN).toISOString(), '2031-01-15T09:00:00.000Z', 'GMT');
+    assert.equal(atWallClock('2031-07-15', '09:00', LDN).toISOString(), '2031-07-15T08:00:00.000Z', 'BST');
+    // 2031-03-30: clocks go 01:00 -> 02:00. 01:30 does not exist.
+    assert.equal(atWallClock('2031-03-30', '00:30', LDN).toISOString(), '2031-03-30T00:30:00.000Z');
+    assert.equal(atWallClock('2031-03-30', '02:30', LDN).toISOString(), '2031-03-30T01:30:00.000Z');
+    // 2031-10-26: clocks go 02:00 -> 01:00. 01:30 happens twice; the first is BST.
+    assert.equal(atWallClock('2031-10-26', '01:30', LDN).toISOString(), '2031-10-26T00:30:00.000Z');
+    assert.equal(atWallClock('2031-10-26', '03:00', LDN).toISOString(), '2031-10-26T03:00:00.000Z');
+    assert.deepEqual(wallClock('2031-07-15T08:00:00Z', LDN), {date: '2031-07-15', time: '09:00', weekday: 2, minutes: 540});
+    assert.equal(atWallClock('2031-07-15', '09:00', 'America/New_York').toISOString(), '2031-07-15T13:00:00.000Z');
+});
+
+test('time helpers', () => {
+    assert.equal(toMinutes('09:30'), 570);
+    assert.equal(toMinutes('24:00'), 1440);
+    assert.ok(Number.isNaN(toMinutes('24:30')));
+    assert.ok(Number.isNaN(toMinutes('9')));
+    assert.equal(fromMinutes(570), '09:30');
+    assert.equal(addDays('2031-12-31', 1), '2032-01-01');
+    assert.equal(weekdayOf('2031-07-15'), 2);
+    assert.ok(isDate('2032-02-29'));
+    assert.ok(!isDate('2031-02-29'));
+    assert.equal(cleanZone('Not/AZone'), LDN);
+    assert.equal(cleanZone('America/New_York'), 'America/New_York');
+});
+
+const SAM = {id: 'sam', hours: {tue: [{from: '09:00', to: '12:00'}, {from: '11:00', to: '13:00'}, {from: '14:00', to: '17:00'}]}, daysOff: [{from: '2031-07-22', to: '2031-07-22'}]};
+const ROOM = {id: 'room', hours: {tue: [{from: '10:00', to: '11:00'}]}};
+const CUT = {id: 'cut', duration: 60, bufferBefore: 0, bufferAfter: 15, step: 30, minNoticeMinutes: 0, maxAdvanceDays: 0};
+const NOW = '2031-07-01T00:00:00Z';
+
+test('opening windows: overlapping ones merge; a day off or a closure empties the day', () => {
+    assert.deepEqual(windowsOn(SAM, '2031-07-15'), [{from: 540, to: 780}, {from: 840, to: 1020}]);
+    assert.deepEqual(windowsOn(SAM, '2031-07-22'), [], 'day off');
+    assert.deepEqual(windowsOn(SAM, '2031-07-15', [{from: '2031-07-14', to: '2031-07-16'}]), [], 'closure');
+    assert.deepEqual(windowsOn(SAM, '2031-07-16'), [], 'no Wednesday hours');
+    assert.deepEqual(windowsOn({hours: {tue: [{from: '10:00', to: '09:00'}, {from: 'x', to: '11:00'}]}}, '2031-07-15'), [], 'nonsense ignored');
+});
+
+test('slots: every step that fits in a window, in the business zone', () => {
+    const [day] = slotsFor({service: CUT, bookables: [SAM], bookings: [], from: '2031-07-15', to: '2031-07-15', now: NOW, tz: LDN});
+    assert.deepEqual(day.slots.map(s => s.time), ['09:00', '09:30', '10:00', '10:30', '11:00', '11:30', '12:00', '14:00', '14:30', '15:00', '15:30', '16:00']);
+    assert.equal(day.slots[0].start, '2031-07-15T08:00:00.000Z');
+    assert.equal(day.slots[0].end, '2031-07-15T09:00:00.000Z');
+});
+
+test('slots: an existing booking and its buffer block the times that would touch them', () => {
+    const booking = {id: 'b1', bookableId: 'sam', status: 'confirmed', ...isoSpan(spanOf(CUT, Date.parse('2031-07-15T09:00:00Z')))};
+    const [day] = slotsFor({service: CUT, bookables: [SAM], bookings: [booking], from: '2031-07-15', to: '2031-07-15', now: NOW, tz: LDN});
+    const times = day.slots.map(s => s.time);
+    // Booked 10:00-11:00 (+15 after, to 11:15). A new 09:00 blocks to 10:15: clash. 11:30 starts after 11:15: fine.
+    assert.ok(!times.includes('09:00') && !times.includes('09:30') && !times.includes('10:00') && !times.includes('10:30') && !times.includes('11:00'));
+    assert.ok(times.includes('11:30'));
+    const cancelled = {...booking, status: 'cancelled'};
+    assert.equal(slotsFor({service: CUT, bookables: [SAM], bookings: [cancelled], from: '2031-07-15', to: '2031-07-15', now: NOW, tz: LDN})[0].slots.length, 12, 'cancelling frees the time');
+    assert.equal(slotsFor({service: CUT, bookables: [SAM], bookings: [booking], from: '2031-07-15', to: '2031-07-15', now: NOW, tz: LDN, ignoreId: 'b1'})[0].slots.length, 12, 'a moved booking does not clash with itself');
+});
+
+test('slots: another bookable\'s booking does not block; busy time from the Calendar does', () => {
+    const other = {id: 'x', bookableId: 'room', status: 'confirmed', startAt: '2031-07-15T08:00:00Z', endAt: '2031-07-15T09:00:00Z'};
+    const busy = {sam: [{startAt: '2031-07-15T13:00:00Z', endAt: '2031-07-15T14:00:00Z'}]};
+    const [day] = slotsFor({service: CUT, bookables: [SAM], bookings: [other], busy, from: '2031-07-15', to: '2031-07-15', now: NOW, tz: LDN});
+    const times = day.slots.map(s => s.time);
+    assert.ok(times.includes('09:00'));
+    assert.ok(!times.includes('14:00') && !times.includes('14:30'), '14:00-15:00 local is busy');
+    assert.ok(times.includes('15:00'));
+});
+
+test('slots: several providers - a time is offered while any of them is free, with who', () => {
+    const [day] = slotsFor({service: CUT, bookables: [SAM, ROOM], bookings: [], from: '2031-07-15', to: '2031-07-15', now: NOW, tz: LDN});
+    assert.deepEqual(day.slots.find(s => s.time === '10:00').bookableIds, ['sam', 'room']);
+    assert.deepEqual(day.slots.find(s => s.time === '09:00').bookableIds, ['sam']);
+    assert.equal(pickBookable(['sam', 'room'], [{bookableId: 'sam', status: 'confirmed', startAt: '2031-07-15T08:00:00Z'}], '2031-07-15', LDN), 'room', 'the less busy one');
+    assert.equal(pickBookable(['sam', 'room'], [], '2031-07-15', LDN), 'sam', 'else the first');
+});
+
+test('slots: notice and how far ahead', () => {
+    const now = '2031-07-15T08:10:00Z';   // 09:10 in London
+    const svc = {...CUT, minNoticeMinutes: 120, maxAdvanceDays: 7};
+    const [day] = slotsFor({service: svc, bookables: [SAM], bookings: [], from: '2031-07-15', to: '2031-07-15', now, tz: LDN});
+    assert.equal(day.slots[0].time, '11:30', 'two hours from 09:10');
+    const later = slotsFor({service: svc, bookables: [SAM], bookings: [], from: '2031-07-29', to: '2031-07-29', now, tz: LDN});
+    assert.equal(later[0].slots.length, 0, 'beyond a week');
+    assert.deepEqual(bookingRange(svc, now, LDN), {first: '2031-07-15', last: '2031-07-22'});
+});
+
+test('slots: the spring-forward night never offers a time that does not exist', () => {
+    const night = {id: 'n', hours: {sun: [{from: '00:00', to: '04:00'}]}};
+    const [day] = slotsFor({service: {...CUT, bufferAfter: 0}, bookables: [night], bookings: [], from: '2031-03-30', to: '2031-03-30', now: '2031-03-01T00:00:00Z', tz: LDN});
+    assert.deepEqual(day.slots.map(s => s.time), ['00:00', '00:30', '02:00', '02:30', '03:00']);
+});
+
+test('isFree: overlap at the edge is not a clash', () => {
+    const b = [{id: 'a', bookableId: 's', status: 'confirmed', blockStart: '2031-07-15T09:00:00Z', blockEnd: '2031-07-15T10:00:00Z'}];
+    const at = (s, e) => ({start: Date.parse(s), end: Date.parse(e), blockStart: Date.parse(s), blockEnd: Date.parse(e)});
+    assert.ok(isFree(at('2031-07-15T10:00:00Z', '2031-07-15T11:00:00Z'), 's', b));
+    assert.ok(!isFree(at('2031-07-15T09:59:00Z', '2031-07-15T11:00:00Z'), 's', b));
+});
+
+function isoSpan(span) {
+    return {startAt: new Date(span.start).toISOString(), endAt: new Date(span.end).toISOString(),
+        blockStart: new Date(span.blockStart).toISOString(), blockEnd: new Date(span.blockEnd).toISOString()};
+}
+
+import {cleanBookable, cleanCustomer, cleanService, slugify} from '../public/lib/clean.js';
+
+test('cleaning: bookables, services and customers', () => {
+    const b = cleanBookable({name: ' Room 1 ', kind: 'resource', hours: {mon: [{from: '09:00', to: '08:00'}, {from: '10:00', to: '12:00'}]}, daysOff: [{from: '2031-01-02'}, {from: 'x'}]});
+    assert.deepEqual(b.errors, {});
+    assert.equal(b.data.name, 'Room 1');
+    assert.deepEqual(b.data.hours.mon, [{from: '10:00', to: '12:00'}]);
+    assert.deepEqual(b.data.daysOff, [{from: '2031-01-02', to: '2031-01-02', label: ''}]);
+    assert.deepEqual(cleanBookable({}).data.hours.tue, [{from: '09:00', to: '17:00'}], 'office hours to start with');
+    assert.ok(cleanBookable({name: ''}).errors.name);
+
+    const s = cleanService({name: 'Hair cut & finish', duration: '45', bookables: ['a', 'a', '']});
+    assert.equal(s.data.slug, 'hair-cut-finish');
+    assert.deepEqual([s.data.duration, s.data.step, s.data.bookables], [45, 45, ['a']]);
+    assert.ok(cleanService({name: 'X'}).errors.bookables);
+    assert.equal(slugify('Café'), 'cafe');
+
+    const c = cleanCustomer({name: 'Sam', email: 'SAM@Example.com ', phone: '07700 900123'});
+    assert.deepEqual(c, {data: {name: 'Sam', email: 'sam@example.com', phone: '07700 900123', notes: ''}, errors: {}});
+    assert.ok(cleanCustomer({name: 'Sam', email: 'nope'}).errors.email);
+    assert.ok(cleanCustomer({name: 'Sam', email: 'a@b.co'}, {phoneRequired: true}).errors.phone);
+    assert.equal(cleanCustomer({name: 'Sam', email: 'a@b.co', phone: '1'}, {askPhone: false}).data.phone, '');
+});
+
+import {PLAIN, holdsOf, placesLeft, whoCanTake} from '../public/lib/slots.js';
+
+// ---- Booking Pro's rules, applied by the free engine ---------------------------------
+
+const TRAINER = {id: 'tr', hours: {tue: [{from: '09:00', to: '12:00'}]}};
+const COURT1 = {id: 'c1', hours: {tue: [{from: '09:00', to: '12:00'}]}};
+const COURT2 = {id: 'c2', hours: {tue: [{from: '09:00', to: '12:00'}]}};
+const LESSON = {id: 'lesson', duration: 60, step: 60, bufferBefore: 0, bufferAfter: 0, minNoticeMinutes: 0, maxAdvanceDays: 0};
+const at = (time) => atWallClock('2031-07-15', time, LDN).toISOString();
+const held = (id, time, extra = {}) => ({id, status: 'confirmed', serviceId: 'lesson', startAt: at(time), endAt: new Date(Date.parse(at(time)) + 3600000).toISOString(), ...extra});
+
+test('companions: a time needs the trainer AND a free court; the booking holds both', () => {
+    const rules = {...PLAIN, companions: [[COURT1, COURT2]]};
+    const bookings = [held('x', '09:00', {bookableId: 'other', holds: ['other', 'c1']}), held('y', '09:00', {bookableId: 'other2', holds: ['other2', 'c2']})];
+    const [day] = slotsFor({service: LESSON, bookables: [TRAINER], bookings, from: '2031-07-15', to: '2031-07-15', now: NOW, tz: LDN, rules});
+    assert.deepEqual(day.slots.map(s => s.time), ['10:00', '11:00'], 'both courts taken at 09:00');
+    const span = spanOf(LESSON, Date.parse(at('10:00')));
+    assert.deepEqual(whoCanTake({service: LESSON, candidates: [TRAINER], companions: rules.companions, span, bookings, rules}), [{bookableId: 'tr', holds: ['tr', 'c1'], left: 1}]);
+    assert.deepEqual(holdsOf({bookableId: 'a'}), ['a']);
+});
+
+test('places: a class takes several people at one start, then is full', () => {
+    const rules = {...PLAIN, capacity: 3};
+    const bookings = [held('a', '09:00', {bookableId: 'tr'}), held('b', '09:00', {bookableId: 'tr'})];
+    let [day] = slotsFor({service: LESSON, bookables: [TRAINER], bookings, from: '2031-07-15', to: '2031-07-15', now: NOW, tz: LDN, rules});
+    assert.equal(day.slots.find(s => s.time === '09:00').left, 1);
+    assert.equal(day.slots.find(s => s.time === '10:00').left, 3);
+    bookings.push(held('c', '09:00', {bookableId: 'tr'}));
+    [day] = slotsFor({service: LESSON, bookables: [TRAINER], bookings, from: '2031-07-15', to: '2031-07-15', now: NOW, tz: LDN, rules});
+    assert.ok(!day.slots.some(s => s.time === '09:00'), 'full');
+    [day] = slotsFor({service: LESSON, bookables: [TRAINER], bookings, from: '2031-07-15', to: '2031-07-15', now: NOW, tz: LDN, rules, includeFull: true});
+    assert.deepEqual(day.slots.find(s => s.time === '09:00'), {start: at('09:00'), end: day.slots[0].end, time: '09:00', bookableIds: [], left: 0, full: true, fullIds: ['tr']});
+    // Another service overlapping the class is still a clash.
+    const other = [held('d', '10:00', {bookableId: 'tr', serviceId: 'massage'})];
+    [day] = slotsFor({service: LESSON, bookables: [TRAINER], bookings: other, from: '2031-07-15', to: '2031-07-15', now: NOW, tz: LDN, rules});
+    assert.ok(!day.slots.some(s => s.time === '10:00'));
+    assert.equal(pickBookable(['sam', 'tr'], [held('a', '09:00', {bookableId: 'tr'})], '2031-07-15', LDN, {serviceId: 'lesson', start: Date.parse(at('09:00'))}), 'tr', 'join the class that runs');
+});
+
+test('a day\'s limit counts sessions; joining a running class is never over it', () => {
+    const dayOf = (ms) => wallClock(ms, LDN).date;
+    const bookings = [held('a', '09:00', {bookableId: 'tr'})];
+    const span10 = spanOf(LESSON, Date.parse(at('10:00')));
+    const span9 = spanOf(LESSON, Date.parse(at('09:00')));
+    assert.equal(placesLeft(span10, 'tr', bookings, [], '', {serviceId: 'lesson', capacity: 1, maxPerDay: 1, dayOf}), 0);
+    assert.equal(placesLeft(span9, 'tr', bookings, [], '', {serviceId: 'lesson', capacity: 2, maxPerDay: 1, dayOf}), 1);
+    assert.equal(placesLeft(span10, 'tr', bookings, [], '', {serviceId: 'lesson', capacity: 1, maxPerDay: 2, dayOf}), 1);
+});

package/plugins/free-tier.lock.json

@@ -1,6 +1,6 @@
 {
   "note": "Written by `make sync-free-tier` in dcms-marketplace. Do not edit these plugins here - edit them there and sync.",
-  "source": "dcms-marketplace@f79220a",
+  "source": "dcms-marketplace@4cdfbe1",
   "plugins": {
     "blog": {
       "version": "1.9.4",
@@ -72,6 +72,49 @@
         "tests/public.test.js": "a6fcdc4ede242aa050ffe5a52f970d6bec1f4a70ae78967eb8a7bdeec73df19d"
       }
     },
+    "booking": {
+      "version": "1.4.0",
+      "files": {
+        "CLAUDE.md": "8e96d41dcbba3adcebf8456a6638e266f559d6fbfb4ba1406645a82cb40ce146",
+        "admin/css/index.css": "4f7731921c0c5038cb1566a6ab2d43ffc35bf9b161e58f87a0cff423e81b47fa",
+        "admin/lib/details.js": "8b37536bfa9ccfcc5265cc957ba8266d3f5f777133e7c0946ae49540f1c80e3c",
+        "admin/lib/diary-layout.js": "d818c79001fb9a9ecc15c96239ba961b0a1d98b9e8fce903eefb57d85adf2a73",
+        "admin/lib/extension-sections.js": "0588ad47660e511b0dd8077bb9c3999c775d97597333a75e87ee12d915bbf00b",
+        "admin/lib/kit.js": "661e9c407bf398694dfa08105590065a6352594d526f3c09c31b180c840045bf",
+        "admin/templates/booking.html": "20b9a3bfe3e5d5bbee613f29be99551b12790fb38f80d119585360cc38e9ec57",
+        "admin/views/booking.js": "4eddf6c0b60dbbba4c6e35352df247a3d34b66ee1d43c51fe2d53f894707348f",
+        "admin/views/bookings.js": "bf17db82ed4d2f5c29ac924dd60dc0b84c8bd9c8ce32da6cbb011527699a56a6",
+        "admin/views/diary.js": "9e8976e67c2232d353b3d9a1ef0d0503cc4d06b710d54d0cba84fb5b796fdfe9",
+        "admin/views/panels.js": "9d1c45e56d2a7a8caa12e9af29545c808ffb88da3ea48397d55aae19e802ec69",
+        "admin/views/people.js": "58cb9cc550b48c959a5572a4d25650ea2b32b658c9d0bf4c244e4abe0277c211",
+        "admin/views/services.js": "122326d222ed16dc8ec903fef6f62f6a7638c31d73c4612b7a8c2ced38358068",
+        "admin/views/settings.js": "299297b47a6509986276a859807a33ea225681d28e0e9cd06cdf36b0f6ec0c11",
+        "collections/booking-bookables.json": "9f1f305eceac3d880413d5477a631e48c1fed7ff389c434f34651f4082ca1a1c",
+        "collections/booking-bookings.json": "fa0b15cc81b4a2114734a0bc8adc4b4d25049d16cf62549b83634cdbeb543b52",
+        "collections/booking-services.json": "cecb500a9215a0eba894e6b4c9ae78f5fbeb209830d07d47050c56c75143f66a",
+        "config.js": "5565fd627481cf809322257cc300a7cbb7ccbf6cae076b4cf8a7453fcf554bd3",
+        "docs/guide.md": "545b050500a09ffdf7bc620e01f0b63bf59e92dfe855ba3201419b0bcc92a1fc",
+        "inject/body.html": "ab55ce945eec2302eb0c836a4626cffa5e091d050c6a59c6f2af332b05570777",
+        "lib/call.js": "7dfa0ae60be87d8f7f26b4360d5c1144322abe66eb61b233ed812e35bb8e59bd",
+        "lib/extensions.js": "8cec28ff8685daad8083b23f034f1c3bf82fd2322943dd19d46570ccdc311105",
+        "lib/mail.js": "cad8f409df62d6e42f0f4024ec364bbe018a62b842fa3f7c38786fd4e7f92408",
+        "lib/store.js": "270161f907c68de39d32758931e86c290582524af4650e722c2c3be209acc875",
+        "plugin.js": "963e8190dbcaec71915d73402648899bb38135b25ec869a659d0938d03868682",
+        "plugin.json": "0ef595cd1925b41194821f97d0e0e0fca5edb20a98a0f97a8a0efd52e8c50c16",
+        "plugin.public.js": "cd607de84ba7cffe384aa40a1a5976277896bf3973baa6415a01a1a4c9e3aca1",
+        "public/booking.css": "8b88989fdd04e50efc1688a2f32fe2e422299d7d13b81bb8fce0cc162fa99df6",
+        "public/booking.js": "7dfc3d205696967013886567f67a867443c2e370bac29019d69911d695fdbade",
+        "public/lib/clean.js": "d591be9ea8462705b7bc8806670027fdd4d6d4764777da08e91a010d27ec1651",
+        "public/lib/page-format.js": "a38454283c2b7256b38ea48578f6df2695a623e0fe2c5d80aae9952e7034a93d",
+        "public/lib/slots.js": "6472e530f3f521e7a08625ed2ee86802a9065cbf2f97c2c7601229f5f032dc07",
+        "public/lib/time.js": "48e13a23e3d7a4916e2097e8f87c03a87d37b71c4ef037a5a16143c6a4185c41",
+        "templates/booking.html": "a4995de46dfdab7e692b56f21347f29c76320cf3b0477889dc3c5d14e0b6dcd7",
+        "tests/admin-diary.test.js": "4e34b447d62b41272ceec49bad9d491ae00dd04f4760d8a7a3046be1912f4abe",
+        "tests/api.test.js": "57ce73f48776e15454794405bae5b9674baeda46a96e4a11d0e253c6a977a764",
+        "tests/public.test.js": "0b7b626d60df5a3d73d7c0077b73f59b62a9fded98ce84a8d93cd32cd0333159",
+        "tests/pure.test.js": "8ba0c8f76b4c9efcc422f39ff29509612544d81f760025a4b9a5594af14e7bcf"
+      }
+    },
     "feedback": {
       "version": "1.1.2",
       "files": {

package/server/routes/api/related.js

@@ -11,6 +11,12 @@
  *
  *   GET /api/related/providers?kind=contact   who can add to a contact: [{id, label, icon, actions}]
  *   GET /api/related?kind=contact&id=<id>     {providers: [{id, label, icon, items, error?}]}
+ *
+ * An action with a `permission` is left out for a viewer whose roles lack it.
+ * `message` (0.103, an email in the mail reader) has actions only: no Tool of
+ * its own to gate on, no record to check, so no GET /api/related for it.
+ *
+ *   GET /api/related/providers?kind=message   [{id, label, icon, actions}] ({email}, {name}, {subject} in urls)
  */
 import {authenticate as defaultAuthenticate} from '../../middleware/auth.js';
 import {getEntry} from '../../services/collections.js';
@@ -45,20 +51,29 @@ export async function relatedRoutes(fastify, opts = {}) {
         return {id: request.user?.id ?? request.user?.sub ?? null, role: request.user?.role ?? null, roles};
     };
     // A kind whose Tool is switched off has nothing to relate to (403, as for a role without it).
-    const mayRead = (user, kind) => isToolEnabled(KINDS[kind].tool)
-        && user.roles.some(r => getPermissionsFor(KINDS[kind].resource, 'read').includes(r));
+    const mayRead = (user, kind) => !KINDS[kind] || (isToolEnabled(KINDS[kind].tool)
+        && user.roles.some(r => getPermissionsFor(KINDS[kind].resource, 'read').includes(r)));
+    const allowed = (user, action) => !action.permission
+        || user.roles.some(r => getPermissionsFor(action.permission.resource, action.permission.action).includes(r));
 
     fastify.get('/providers', {preHandler: [authenticate]}, async (request, reply) => {
         const kind = String(request.query?.kind ?? '');
         if (!RELATED_KINDS.includes(kind)) return reply.code(400).send({error: `kind must be one of ${RELATED_KINDS.join(', ')}`});
-        if (!mayRead(viewer(request), kind)) return reply.code(403).send({error: 'Forbidden'});
-        return getRelatedProviders(kind).map(({id, label, icon, actions}) => ({id, label, icon, actions}));
+        const user = viewer(request);
+        if (!mayRead(user, kind)) return reply.code(403).send({error: 'Forbidden'});
+        return getRelatedProviders(kind)
+            .map(({id, label, icon, actions}) => ({
+                id, label, icon,
+                actions: actions.filter(a => allowed(user, a)).map(({label, icon, url}) => ({label, icon, url}))
+            }))
+            // A provider with only actions, none of them this viewer's, has nothing to offer.
+            .filter(p => kind !== 'message' || p.actions.length);
     });
 
     fastify.get('/', {preHandler: [authenticate]}, async (request, reply) => {
         const kind = String(request.query?.kind ?? '');
         const id = String(request.query?.id ?? '');
-        if (!RELATED_KINDS.includes(kind) || !id) return reply.code(400).send({error: 'kind and id are required'});
+        if (!RELATED_KINDS.includes(kind) || !KINDS[kind] || !id) return reply.code(400).send({error: 'kind and id are required'});
         const user = viewer(request);
         if (!mayRead(user, kind)) return reply.code(403).send({error: 'Forbidden'});
 

package/server/server.js

@@ -593,8 +593,8 @@ await app.register(relatedRoutes, {prefix: '/api/related'});
 // site would simply never see Notes or Todo. Registered items are placed at
 // render time on every site (placeTools() in admin/js/lib/sidebar-grouping.js):
 // in the Tools folder by default, or wherever an admin has moved them.
-// `group: 'Core'` gathers them in a Core sub-folder (Tools -> Core -> Notes),
-// apart from the marketplace plugins' Tools, which sit directly in Tools.
+// The registry supplies purpose-based groups shared with marketplace Tools;
+// an admin's saved placement always takes precedence.
 //
 // `permission` is what hides each one from a role that cannot use it; the
 // renderer filters on it.
@@ -610,7 +610,7 @@ const coreToolItems = [
     {text: 'SEO', url: '#/seo', icon: 'search', permission: 'seo', countUrl: '/api/seo/count'}
 ];
 for (const item of coreToolItems) {
-    if (isToolEnabled(item.permission)) registerSidebarItem({group: 'Core', item: {source: 'Built in', ...item}});
+    if (isToolEnabled(item.permission)) registerSidebarItem({item: {source: 'Built in', ...item}});
 }
 // Todo's to-dos on the calendar (registered when routes/api/todo.js loads).
 if (!isToolEnabled('todo')) {

package/server/services/hooks.js

@@ -70,6 +70,19 @@ export async function registerMenuLocation(slot, def) {
 
 const _registeredSidebarItems = [];
 
+/** Purpose-based defaults shared by built-in and marketplace Tools. Match URLs,
+ * so renamed labels and Pro replacements retain the same starting place.
+ * Unknown plugins remain directly in Tools until they declare their own group.
+ */
+const TOOL_GROUPS = new Map(Object.entries({
+    Productivity: ['#/notes', '#/todo', '#/plugins/calendar', '#/plugins/waypoint-pro'],
+    Communication: ['#/contacts', '#/plugins/contacts-pro', '#/plugins/mail-reader', '#/plugins/email-pro', '#/plugins/messages'],
+    Marketing: ['#/analytics', '#/seo', '#/plugins/analytics-pro/dashboard', '#/plugins/social', '#/plugins/feedback', '#/plugins/surveys'],
+    Publishing: ['#/plugins/blog', '#/plugins/blog-pro', '#/plugins/docs', '#/plugins/theme-roller'],
+    Business: ['#/plugins/shopping-cart', '#/plugins/booking', '#/plugins/invoice', '#/job-board', '#/plugins/garage'],
+    Maintenance: ['#/plugins/security', '#/plugins/security-pro', '#/plugins/security-pro/my-2fa', '#/plugins/backup-pro', '#/plugins/data-transfer']
+}).flatMap(([group, urls]) => urls.map(url => [url, group])));
+
 /**
  * Register a Tool's sidebar entry. Entries are placed into the rendered admin
  * sidebar at render time - they are NOT persisted into menu JSON - so plugins
@@ -93,10 +106,12 @@ export function registerSidebarItem(opts) {
         throw new Error('registerSidebarItem: opts.item.text is required');
     }
     const {folder: itemFolder, group: itemGroup, ...item} = opts.item;
-    const group = [opts.group, itemGroup].find(g => typeof g === 'string' && g.trim());
+    const folder = opts.folder || itemFolder || DEFAULT_TOOL_FOLDER;
+    const defaultGroup = folder === DEFAULT_TOOL_FOLDER && !opts.parent ? TOOL_GROUPS.get(item.url) : undefined;
+    const group = [opts.group, itemGroup, defaultGroup].find(g => typeof g === 'string' && g.trim());
     _registeredSidebarItems.push({
         parent: opts.parent || null,
-        folder: opts.folder || itemFolder || DEFAULT_TOOL_FOLDER,
+        folder,
         ...(group && {group: group.trim()}),
         item
     });
@@ -270,7 +285,10 @@ export function getCalendarSources() {
 // provider per kind; GET /api/related asks each one for what relates to one
 // record, after core has checked the viewer may see that record at all.
 
-export const RELATED_KINDS = ['contact', 'note'];
+// 'message' (0.103): an email open in the mail reader. It has no record id core
+// can check, so only `actions` apply - `{email}`, `{name}` and `{subject}` in a
+// url become the sender's address and name and the subject - and there is no list.
+export const RELATED_KINDS = ['contact', 'note', 'message'];
 const _relatedProviders = new Map(); // kind -> Map(id -> provider)
 
 /**
@@ -279,27 +297,36 @@ const _relatedProviders = new Map(); // kind -> Map(id -> provider)
  * `list({id, user})` resolves to `[{id, title, when?, startAt?, allDay?, meta?, url?, past?}]`
  * - with `startAt` and no `when`, the admin writes the time in the reader's zone.
  * `actions` are shown in the record's menu, `{id}` in a url replaced by the
- * record's id: `[{label, icon?, url}]`.
+ * record's id: `[{label, icon?, url, permission?}]`. `permission`
+ * (`{resource, action}`) shows the action only to roles that hold it.
  *
- * @param {'contact'|'note'} kind
+ * @param {'contact'|'note'|'message'} kind
  * @param {{id: string, label: string, icon?: string, list: Function, actions?: object[], owner?: string}} provider
  * @returns {boolean}
  */
 export function registerRelatedItems(kind, provider = {}) {
   if (!RELATED_KINDS.includes(kind)) return false;
   const {id, list} = provider;
-  if (typeof id !== 'string' || !id || typeof list !== 'function') return false;
+  if (typeof id !== 'string' || !id) return false;
+  if (kind !== 'message' && typeof list !== 'function') return false;
   if (!_relatedProviders.has(kind)) _relatedProviders.set(kind, new Map());
   const actions = (Array.isArray(provider.actions) ? provider.actions : [])
     .filter(a => a && typeof a.label === 'string' && typeof a.url === 'string' && a.url.startsWith('#/'))
-    .map(a => ({label: a.label, icon: typeof a.icon === 'string' ? a.icon : 'arrow-right', url: a.url}));
+    .map(a => ({
+      label: a.label,
+      icon: typeof a.icon === 'string' ? a.icon : 'arrow-right',
+      url: a.url,
+      ...(a.permission && typeof a.permission.resource === 'string'
+        ? {permission: {resource: a.permission.resource, action: typeof a.permission.action === 'string' ? a.permission.action : 'read'}}
+        : {})
+    }));
   _relatedProviders.get(kind).set(id, {
     id,
     label: typeof provider.label === 'string' && provider.label.trim() ? provider.label.trim() : id,
     icon: typeof provider.icon === 'string' ? provider.icon : 'link',
     owner: typeof provider.owner === 'string' ? provider.owner : 'core',
     actions,
-    list
+    list: typeof list === 'function' ? list : () => []
   });
   return true;
 }