@acms-subir/core 0.3.21 → 0.3.23

package/src/lib/calendar/requests.ts

@@ -0,0 +1,284 @@
+import { userConfig } from 'virtual:acms-config';
+import type { ContentRepository } from '../repo/types';
+import type { CalEvent, EventRequest } from '../schema';
+import { EventLocation } from '../schema';
+import { ApiError } from '../api';
+import { applyEventUpdate, saveEvent, type SaveHooks } from '../content-service';
+import { CALENDAR } from './config';
+import { cancelOccurrence, restoreOccurrence, uniqueSlug } from './schedule';
+import { eventDeleted } from './hooks';
+import { waitUntilFrom } from '../webhooks';
+import { kickEmail } from '../email/service';
+
+// Members' event requests: the rules behind "My events". A member whose role
+// holds "Request events" (events.request) asks for a new event (a draft that
+// waits for approval) or suggests changes to an event they host (staged on
+// the live event, which stays as it is). Staff who can "Publish content"
+// approve or decline. Hosts may always cancel or restore single dates of
+// their own events, which applies at once like it does for staff.
+//
+// Everything here checks who is acting, so the built-in member pages and a
+// site's own pages (through @acms-subir/core/server) share the same rules.
+
+/** where the built-in member pages live (acms({ members })); `notify` hears about new requests */
+export const MEMBERS: { enabled: boolean; base: string; notify: string[] } = { enabled: false, base: '/members', notify: [], ...(userConfig.members ?? {}) };
+export const memberEventsPath = () => `${MEMBERS.base}/events`;
+
+/** who is acting: currentUser() from @acms-subir/core/server fits */
+export interface Actor { id: string; can(permission: string): boolean }
+
+/** what a member may fill in; staff can change anything else in the admin */
+export interface EventRequestInput {
+  title: string;
+  /** plain text; blank lines start new paragraphs */
+  description?: string;
+  /** YYYY-MM-DDTHH:mm (or YYYY-MM-DD when allDay), in the site's time zone */
+  start: string;
+  end?: string;
+  allDay?: boolean;
+  /** '' (once), or FREQ=DAILY|WEEKLY|MONTHLY with an optional INTERVAL and COUNT */
+  repeat?: string;
+  /** where it happens, as text */
+  where?: string;
+  /** one of the site's own calendars */
+  calendarId?: string;
+  /** the site's custom event fields (private ones are staff-only and ignored) */
+  fields?: Record<string, string>;
+  /** a message for staff; never public */
+  note?: string;
+}
+
+const LIMITS = { title: 200, description: 5000, where: 300, note: 1000, field: 500, pending: 20 };
+const REPEAT = /^FREQ=(DAILY|WEEKLY|MONTHLY)(;INTERVAL=[1-9]\d?)?(;COUNT=[1-9]\d{0,2})?$/;
+const live = (e: CalEvent) => e.status === 'published' || e.status === 'scheduled';
+const text = (v: unknown, max: number) => String(v ?? '').replace(/\r\n?/g, '\n').replace(/[\u0000-\u0009\u000b-\u001f\u007f]/g, '').trim().slice(0, max);
+/** one line: titles and places end up in email subjects and headings */
+const line = (v: unknown, max: number) => text(v, max).replace(/\s+/g, ' ');
+const esc = (s: string) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!));
+
+/** plain text → the editor's document and its HTML (escaped: members are the public) */
+export function textToBody(value: string): { bodyJson: string; bodyHtml: string } {
+  const paras = value.split(/\n{2,}/).map((p) => p.trim()).filter(Boolean);
+  if (!paras.length) return { bodyJson: '', bodyHtml: '' };
+  const content = paras.map((p) => {
+    const lines = p.split('\n');
+    return { type: 'paragraph', content: lines.flatMap((l, i) => [...(i ? [{ type: 'hardBreak' }] : []), ...(l ? [{ type: 'text', text: l }] : [])]) };
+  });
+  return { bodyJson: JSON.stringify({ type: 'doc', content }), bodyHtml: paras.map((p) => `<p>${p.split('\n').map(esc).join('<br>')}</p>`).join('') };
+}
+
+/** the description a member typed back from an event (for editing a request) */
+export function bodyToText(e: Pick<CalEvent, 'bodyHtml'>): string {
+  return e.bodyHtml
+    .replace(/<br\s*\/?>/gi, '\n').replace(/<\/p>\s*<p[^>]*>/gi, '\n\n').replace(/<[^>]+>/g, '')
+    .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&').trim();
+}
+
+function requireMember(who: Actor | null): asserts who is Actor {
+  if (!who) throw new ApiError(401, 'Sign in to continue.');
+  if (!who.can('events.request')) throw new ApiError(403, 'Your role doesn’t include “Request events”. Ask the site’s team if you need it.');
+}
+function requireApprover(who: Actor | null): asserts who is Actor {
+  if (!who) throw new ApiError(401, 'Sign in to continue.');
+  if (!who.can('content.publish')) throw new ApiError(403, 'Your role doesn’t include “Publish content”, which approving requests needs.');
+}
+/** a host of this event, or the member who asked for it */
+export const isHost = (e: CalEvent, userId: string) => e.hostIds.includes(userId) || (e.request?.by === userId && e.request.kind === 'new');
+async function hostedEvent(repo: ContentRepository, who: Actor, id: string) {
+  const e = await repo.getEvent(id);
+  if (!e || e.status === 'archived' || !isHost(e, who.id)) throw new ApiError(404, 'Event not found.');
+  return e;
+}
+
+/** the request form's input → event fields, validated (`current`: the event being edited, whose own values may be kept) */
+async function clean(repo: ContentRepository, input: EventRequestInput, current?: CalEvent) {
+  const title = line(input.title, LIMITS.title);
+  if (!title) throw new ApiError(400, 'Give the event a title.');
+  const start = text(input.start, 16), allDay = input.allDay === true;
+  if (!(allDay ? /^\d{4}-\d{2}-\d{2}$/ : /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/).test(start)) throw new ApiError(400, 'Pick a date and start time.');
+  const end = text(input.end, 16);
+  if (end && !(allDay ? /^\d{4}-\d{2}-\d{2}$/ : /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/).test(end)) throw new ApiError(400, 'Pick a valid end time.');
+  if (end && end < start) throw new ApiError(400, 'The end has to come after the start.');
+  const rrule = text(input.repeat, 80).toUpperCase();
+  // a pattern staff set (weekly on two days, yearly…) may be kept as it is
+  if (rrule && !REPEAT.test(rrule) && rrule !== current?.rrule.toUpperCase()) throw new ApiError(400, 'Choose how often it repeats from the list.');
+  // members pick among the public calendars; any other calendars staff put it in stay
+  const calendars = await repo.listCalendars();
+  const open = new Set(calendars.filter((c) => c.kind === 'native' && c.visibility === 'public').map((c) => c.id));
+  const chosen = input.calendarId ? String(input.calendarId) : '';
+  if (chosen && !open.has(chosen) && !current?.calendarIds.includes(chosen)) throw new ApiError(400, 'Choose a calendar from the list.');
+  const calendarIds = current && (!chosen || current.calendarIds.includes(chosen))
+    ? current.calendarIds
+    : [...(current?.calendarIds ?? []).filter((id) => !open.has(id)), ...(chosen ? [chosen] : [])];
+  const fields: Record<string, string> = {};
+  for (const f of CALENDAR.eventFields) {
+    if (f.private || input.fields?.[f.key] === undefined) continue;
+    const value = text(input.fields[f.key], LIMITS.field);
+    if (f.type === 'select' && value && !f.options.includes(value)) throw new ApiError(400, `Choose ${f.label} from the list.`);
+    fields[f.key] = value; // '' clears it
+  }
+  return { title, start, end: end || undefined, allDay, rrule, calendarIds, fields, description: text(input.description, LIMITS.description), where: line(input.where, LIMITS.where) };
+}
+const filled = (fields: Record<string, string>) => Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== ''));
+
+const hooksFor = (h: SaveHooks): SaveHooks => ({ url: h.url, locals: h.locals });
+const pending = (by: string, kind: EventRequest['kind'], note: string, created: boolean): EventRequest =>
+  ({ kind, state: 'pending', by, at: Date.now(), note, reply: '', reviewedBy: '', reviewedAt: 0, created });
+/** a host's own suggestion waiting on this live event (its staged draft is theirs) */
+const hostChanges = (e: CalEvent) => e.request?.kind === 'changes' && e.request.state === 'pending';
+
+/** events this person hosts, plus their own requests, soonest first (archived ones left out) */
+export async function hostedEvents(repo: ContentRepository, userId: string): Promise<CalEvent[]> {
+  return (await repo.listEvents()).filter((e) => e.status !== 'archived' && isHost(e, userId)).sort((a, b) => a.startAt - b.startAt);
+}
+
+/** requests waiting for staff, oldest first */
+export async function pendingRequests(repo: ContentRepository): Promise<CalEvent[]> {
+  return (await repo.listEvents()).filter((e) => e.request?.state === 'pending').sort((a, b) => a.request!.at - b.request!.at);
+}
+
+/** a member asks for a new event: a draft they host, waiting for approval */
+export async function submitEventRequest(repo: ContentRepository, who: Actor | null, input: EventRequestInput, hooks: SaveHooks): Promise<CalEvent> {
+  requireMember(who);
+  if (!await repo.email.rateLimit(`event-request:${who.id}`, 20, 3_600_000)) throw new ApiError(429, 'That’s a lot of requests in an hour. Try again later.', 3600);
+  const open = (await hostedEvents(repo, who.id)).filter((e) => e.request?.state === 'pending').length;
+  if (open >= LIMITS.pending) throw new ApiError(429, 'You have many requests waiting already. Wait for the team to answer them first.');
+  const c = await clean(repo, input);
+  const created = await repo.createEvent({
+    title: c.title, slug: await uniqueSlug(repo, c.title), start: c.start, allDay: c.allDay, status: 'draft',
+    calendarIds: c.calendarIds, fields: filled(c.fields), ...textToBody(c.description),
+    location: EventLocation.parse({ name: c.where }),
+    hostIds: [who.id], request: pending(who.id, 'new', text(input.note, LIMITS.note), true),
+  });
+  // times and repeat go through the editor's own validation
+  await saveEvent(repo, created.id, { start: c.start, end: c.end, allDay: c.allDay, rrule: c.rrule }, hooksFor(hooks));
+  await notifyStaff(repo, created.id, hooks);
+  return (await repo.getEvent(created.id))!;
+}
+
+/**
+ * A host edits their request, or suggests changes to their live event. A
+ * request that hasn't gone live is updated and (re)sent for approval; a live
+ * event keeps showing what it shows until staff approve the changes.
+ */
+export async function updateEventRequest(repo: ContentRepository, who: Actor | null, id: string, input: EventRequestInput, hooks: SaveHooks): Promise<CalEvent> {
+  requireMember(who);
+  const e = await hostedEvent(repo, who, id);
+  // staff have unpublished edits of their own on this live event: don't mix a
+  // host's suggestion into them (declining it would throw both away)
+  if (live(e) && e.draft && !hostChanges(e)) throw new ApiError(409, 'The team is editing this event right now. Try again later.');
+  if (!await repo.email.rateLimit(`event-request:${who.id}`, 20, 3_600_000)) throw new ApiError(429, 'That’s a lot of changes in an hour. Try again later.', 3600);
+  // what the host sees is the event with their own waiting changes on top
+  const current = (hostChanges(e) ? { ...e, ...(e.draft ?? {}) } : e) as CalEvent;
+  const c = await clean(repo, input, current);
+  const data: Parameters<typeof saveEvent>[2] = { title: c.title, start: c.start, end: c.end, allDay: c.allDay, rrule: c.rrule, calendarIds: c.calendarIds,
+    fields: filled({ ...current.fields, ...c.fields }) };
+  // untouched description or place: keep what staff may have added (formatting, images, address, map pin)
+  if (c.description !== bodyToText(current)) Object.assign(data, textToBody(c.description));
+  if (c.where !== current.location.name) data.location = EventLocation.parse({ name: c.where });
+  // live: saveEvent stages the edit (the event's own draft); not live: it writes it
+  await saveEvent(repo, id, data, hooksFor(hooks));
+  await repo.setEventRequest(id, pending(who.id, live(e) ? 'changes' : 'new', text(input.note, LIMITS.note), !live(e) && e.request?.created === true));
+  await notifyStaff(repo, id, hooks);
+  return (await repo.getEvent(id))!;
+}
+
+/** a host takes back a request: a new event that never went live is deleted; suggested changes are dropped */
+export async function withdrawEventRequest(repo: ContentRepository, who: Actor | null, id: string, hooks: SaveHooks): Promise<{ deleted: boolean }> {
+  requireMember(who);
+  const e = await hostedEvent(repo, who, id);
+  if (!e.request) throw new ApiError(400, 'There’s no request on this event to withdraw.');
+  // only an event the member's own request made is deleted; a draft staff wrote stays
+  if (e.request.kind === 'new' && e.request.created && !live(e) && !e.publishedAt) {
+    await repo.deleteEvent(id);
+    await eventDeleted(repo, e, { waitUntil: waitUntilFrom(hooks.locals) });
+    return { deleted: true };
+  }
+  if (e.request.kind === 'changes') await repo.discardEventDraft(id);
+  await repo.setEventRequest(id, null);
+  return { deleted: false };
+}
+
+/** the request staff are answering, unchanged since they opened it (`seen`: its `at`) */
+async function answerable(repo: ContentRepository, id: string, seen?: number) {
+  const e = await repo.getEvent(id);
+  if (!e?.request || e.request.state !== 'pending') throw new ApiError(409, 'This request was already answered or withdrawn.');
+  if (seen !== undefined && e.request.at !== seen) throw new ApiError(409, 'This request changed after you opened it. Look at it again, then answer.');
+  return e as CalEvent & { request: EventRequest };
+}
+
+/** staff approve: a new event is published; suggested changes go live. Pass `seen` (the request's `at` they reviewed) so later edits aren't approved unseen. */
+export async function approveEventRequest(repo: ContentRepository, who: Actor | null, id: string, hooks: SaveHooks, seen?: number): Promise<CalEvent> {
+  requireApprover(who);
+  const e = await answerable(repo, id, seen);
+  const h = { ...hooksFor(hooks), canPublish: true };
+  if (e.request.kind === 'changes') { if (e.draft) await applyEventUpdate(repo, id, h); }
+  else if (!live(e)) await saveEvent(repo, id, { status: 'published' }, h);
+  await repo.setEventRequest(id, null);
+  await notifyHost(repo, e, 'approved', '', hooks);
+  return (await repo.getEvent(id))!;
+}
+
+/** staff decline, with a note for the host: a new request stays a draft they can edit and resend; suggested changes are dropped */
+export async function declineEventRequest(repo: ContentRepository, who: Actor | null, id: string, reply: string, hooks: SaveHooks, seen?: number): Promise<CalEvent> {
+  requireApprover(who);
+  const e = await answerable(repo, id, seen);
+  if (e.request.kind === 'changes') await repo.discardEventDraft(id);
+  const answer = text(reply, LIMITS.note);
+  await repo.setEventRequest(id, { ...e.request, state: 'declined', reply: answer, reviewedBy: who.id, reviewedAt: Date.now() });
+  await notifyHost(repo, e, 'declined', answer, hooks);
+  return (await repo.getEvent(id))!;
+}
+
+/** a host clears a declined answer they've read (a declined new request stays as a draft) */
+export async function dismissEventRequest(repo: ContentRepository, who: Actor | null, id: string): Promise<void> {
+  if (!who) throw new ApiError(401, 'Sign in to continue.');
+  const e = await hostedEvent(repo, who, id);
+  if (e.request?.state === 'declined' && e.request.kind === 'changes') await repo.setEventRequest(id, null);
+}
+
+/** hosts cancel or restore one date of their own event at once (no permission needed beyond hosting it) */
+export async function setHostedOccurrence(repo: ContentRepository, who: Actor | null, id: string, key: string, cancelled: boolean, hooks: SaveHooks): Promise<CalEvent> {
+  if (!who) throw new ApiError(401, 'Sign in to continue.');
+  const e = await hostedEvent(repo, who, id);
+  if (!e.hostIds.includes(who.id)) throw new ApiError(404, 'Event not found.');
+  return (cancelled ? cancelOccurrence : restoreOccurrence)(repo, id, key, hooksFor(hooks));
+}
+
+/** staff set who hosts an event (Team members only) */
+export async function setEventHosts(repo: ContentRepository, who: Actor | null, id: string, hostIds: string[]): Promise<CalEvent> {
+  if (!who) throw new ApiError(401, 'Sign in to continue.');
+  if (!who.can('content.edit')) throw new ApiError(403, 'Your role doesn’t include “Create and edit content”.');
+  const e = await repo.getEvent(id);
+  if (!e) throw new ApiError(404, 'Event not found.');
+  const known = new Set((await repo.listUsers()).map((u) => u.id));
+  const ids = [...new Set(hostIds)].filter((h) => known.has(h)).slice(0, 10);
+  await repo.setEventHosts(id, ids);
+  return (await repo.getEvent(id))!;
+}
+
+// ---- email ------------------------------------------------------------
+
+/** staff: "New event request" / "Changes to review" (to members.notify, else the owners) */
+async function notifyStaff(repo: ContentRepository, id: string, hooks: SaveHooks) {
+  const e = await repo.getEvent(id);
+  if (!e?.request) return;
+  const to = MEMBERS.notify.length ? MEMBERS.notify : (await repo.listUsers()).filter((u) => u.role === 'owner' && u.email).map((u) => u.email);
+  await queue(repo, e, to, e.request.kind === 'changes' ? 'staff-changes' : 'staff-new', hooks);
+}
+/** the host who asked: "approved" / "declined" (with staff's reply) */
+async function notifyHost(repo: ContentRepository, e: CalEvent, kind: 'approved' | 'declined', reply: string, hooks: SaveHooks) {
+  const by = e.request?.by ? await repo.getUser(e.request.by) : null;
+  if (by?.email) await queue(repo, e, [by.email], kind, hooks, reply);
+}
+async function queue(repo: ContentRepository, e: CalEvent, to: string[], kind: string, hooks: SaveHooks, reply = '') {
+  if (!to.length) return;
+  // like booking emails: the latest saved email settings, or 0 for environment-only setups
+  const version = (await repo.email.config().catch(() => null))?.version ?? 0;
+  const at = e.request?.at ?? Date.now();
+  for (const recipient of to) {
+    await repo.email.enqueue({ dedupe: `event-request:${e.id}:${at}:${kind}:${recipient}`, kind: 'event-request', recipient,
+      payload: JSON.stringify({ eventId: e.id, kind, at, reply }), configVersion: version, expiresAt: Date.now() + 7 * 86_400_000 });
+  }
+  await kickEmail(repo, hooks.locals, waitUntilFrom(hooks.locals)).catch(() => {});
+}

package/src/lib/calendar/schedule.ts

@@ -16,7 +16,7 @@ import { rruleMap, WEEKDAY_CODES, weekdayOf } from './rrule';
 import { eventDeleted } from './hooks';
 import { waitUntilFrom } from '../webhooks';
 
-async function uniqueSlug(repo: ContentRepository, title: string) {
+export async function uniqueSlug(repo: ContentRepository, title: string) {
   const base = slugify(title) || 'event';
   let slug = base;
   for (let n = 2; await repo.getEventBySlug(slug); n++) slug = `${base}-${n}`;

package/src/lib/editor/auth.ts

@@ -1,7 +1,8 @@
 import { AUTH } from '../auth/config';
 import { validateMobileBinding, authEnvironment, ClerkUnavailableError } from '../auth/request';
 import type { ClerkBinding } from '../auth/store';
-import { Role } from '../schema';
+import { isStaffRole } from '../roles';
+import type { Role } from '../schema';
 import { createHmac } from 'node:crypto';
 import { env } from '../env';
 import { sha256Hex } from '../api-keys';
@@ -161,12 +162,13 @@ async function pair(now: number) {
 }
 async function liveUser(repo: ContentRepository, id: string, sessionVersion: number) {
   const [user, version] = await Promise.all([repo.getUser(id), repo.email.sessionVersion(id)]);
-  return user && version === sessionVersion ? user : null;
+  // only staff hold app tokens: someone moved to a site role without admin access loses theirs
+  return user && version === sessionVersion && isStaffRole(user.role) ? user : null;
 }
 function tokenResponse(t: { access: string; refresh: string }, user: { id: string; name: string; email: string; role: string }, device: { id: string; name: string }): TokenResponse {
   return { access_token: t.access, token_type: 'Bearer', expires_in: Math.floor(EDITOR.accessTokenMs / 1000), refresh_token: t.refresh,
     refresh_token_expires_in: Math.floor(EDITOR.refreshTokenMs / 1000),
-    user: { id: user.id, name: user.name, email: user.email, role: Role.parse(user.role) }, device };
+    user: { id: user.id, name: user.name, email: user.email, role: user.role }, device };
 }
 
 async function mobileBindingActive(...args: Parameters<typeof validateMobileBinding>) {

package/src/lib/editor/schemas.ts

@@ -4,7 +4,8 @@ import { Booking, BookingLink, Calendar, LinksAvatarShape, LinksAvatarFit, Links
 
 // Response shapes of the editor-app API (OpenAPI components, client types).
 const str = z.string(), bool = z.boolean(), num = z.number(), date = str.datetime();
-const role = z.enum(['contributor', 'author', 'editor', 'administrator', 'owner']);
+// a core role (owner, administrator, editor, author, contributor) or a staff role the site defines
+const role = str.min(1);
 const Pagination = z.object({ page: num.int(), limit: num.int(), nextPage: num.int().nullable() });
 const User = z.object({ id: str, name: str, email: str, role });
 

package/src/lib/editor/store.ts

@@ -1,4 +1,5 @@
-import { Role } from '../schema';
+import { isStaffRole } from '../roles';
+import type { Role } from '../schema';
 import type { SqlDriver } from '../repo/sql';
 
 type Row = Record<string, unknown>;
@@ -115,10 +116,11 @@ export class EditorStore {
       FROM editor_tokens t JOIN editor_devices d ON d.id=t.device_id JOIN users u ON u.id=d.user_id
       WHERE t.hash=? AND t.kind='access' AND t.expires_at>? AND d.revoked_at IS NULL`, [hash, now]);
     const r = rows[0];
-    if (!r) return null;
+    // only staff use the app: a role without admin access (or one the site removed) gets nothing
+    if (!r || !isStaffRole(String(r.u_role))) return null;
     // first use proves the app received this pair (ends the refresh grace)
     if (r.t_used == null) await this.run('UPDATE editor_tokens SET used_at=? WHERE hash=? AND used_at IS NULL', [now, hash]);
-    return { device: device(r), user: { id: String(r.user_id), name: String(r.u_name), email: String(r.u_email), role: Role.parse(r.u_role), sessionVersion: Number(r.u_sv) } };
+    return { device: device(r), user: { id: String(r.user_id), name: String(r.u_name), email: String(r.u_email), role: String(r.u_role), sessionVersion: Number(r.u_sv) } };
   }
   /** the device a token (access or refresh) belongs to, for revocation */
   async deviceForToken(hash: string): Promise<string | null> {

package/src/lib/email/service.ts

@@ -1,7 +1,8 @@
 import type { ContentRepository } from '../repo/types';
 import { resolveConfig, decrypt, encrypt, runtimeValue } from './config';
 import { sendWithProvider } from './providers';
-import { accountMail, canonicalOrigin, guestCodeMail, EmailLinkError } from './templates';
+import { accountMail, canonicalOrigin, eventRequestMail, guestCodeMail, EmailLinkError } from './templates';
+import { formatDate } from '../dates';
 import { bookingMail } from '../booking/service';
 import type { EmailJob, Mail } from './types';
 
@@ -31,6 +32,18 @@ async function render(repo: ContentRepository, job: EmailJob, locals?: unknown,
     const raw = decrypt<string>(String(token.encrypted), `token:${token.id}`, locals);
     return accountMail(payload.purpose, job.recipient, settings.siteTitle, `${origin}/account/${payload.purpose}?token=${encodeURIComponent(raw)}`);
   }
+  if (job.kind === 'event-request') {
+    const p = JSON.parse(job.payload) as { eventId: string; kind: 'staff-new' | 'staff-changes' | 'approved' | 'declined'; at: number; reply: string };
+    const e = await repo.getEvent(p.eventId);
+    if (!e) return null;
+    const staff = p.kind.startsWith('staff');
+    // staff hear only about requests still waiting (not withdrawn or already answered)
+    if (staff && (e.request?.state !== 'pending' || e.request.at !== p.at)) return null;
+    const by = e.request?.by ? await repo.getUser(e.request.by) : null;
+    const { memberEventsPath, MEMBERS } = await import('../calendar/requests');
+    const url = staff ? `${origin}/admin/calendar/events/${e.id}` : `${origin}${MEMBERS.enabled ? memberEventsPath() : '/'}`;
+    return eventRequestMail(p.kind, job.recipient, settings.siteTitle, { title: e.title, when: formatDate(e.startAt, settings), by: by?.name ?? '', note: e.request?.note ?? '' }, p.reply, url);
+  }
   if (job.kind === 'welcome' || job.kind === 'password-changed') return accountMail(job.kind, job.recipient, settings.siteTitle, `${origin}/admin/login`);
   if (job.kind === 'email-changed') return accountMail(job.kind, job.recipient, settings.siteTitle);
   return null;
@@ -57,9 +70,9 @@ export async function dispatchEmail(repo: ContentRepository, locals?: unknown, l
       }
       await repo.email.pin(j,resolved.provider,resolved.fingerprint,config?.version || 0);
       if (await repo.email.suppressed(j.recipient)) { await repo.email.finish(j,{state:'suppressed',error:'Recipient is suppressed after a bounce or complaint.'}); continue; }
-      if (j.kind === 'booking') {
+      if (j.kind === 'booking' || j.kind === 'event-request') {
         const payload = JSON.parse(j.payload);
-        if ((payload.kind === 'reminder' && !current.config.reminders) || (payload.kind === 'staff-new' && !current.config.staffNotifications)) {
+        if ((payload.kind === 'reminder' && !current.config.reminders) || (String(payload.kind).startsWith('staff-') && !current.config.staffNotifications)) {
           await repo.email.finish(j,{state:'cancelled',error:'Optional notification disabled.'}); continue;
         }
       }

package/src/lib/email/store.ts

@@ -141,7 +141,9 @@ export class EmailStore {
       { sql: "UPDATE email_tokens SET encrypted='' WHERE expires_at <= ? OR used_by != '' OR revoked=1", args:[now] },
     ]);
   }
-  async sessionVersion(id: string): Promise<number | null> { const r = await (await this.getDriver()).all('SELECT session_version FROM users WHERE id=?', [id]); return r[0] ? Number(r[0].session_version) : null; }
+  async sessionVersion(id: string): Promise<number | null> { return (await this.sessionState(id))?.version ?? null; }
+  /** the session version and role in one read (every signed-in request asks for both) */
+  async sessionState(id: string): Promise<{ version: number; role: string } | null> { const r = await (await this.getDriver()).all('SELECT session_version, role FROM users WHERE id=?', [id]); return r[0] ? { version: Number(r[0].session_version), role: String(r[0].role) } : null; }
   async invitations(): Promise<Invitation[]> {
     return (await (await this.getDriver()).all("SELECT id,email,name,role,expires_at,created_at,invited_by,CASE WHEN revoked=1 THEN 'revoked' WHEN used_by!='' THEN 'accepted' WHEN expires_at < ? THEN 'expired' ELSE 'pending' END state FROM email_tokens WHERE purpose='invite' ORDER BY created_at DESC LIMIT 100", [Date.now()])).map((r) => ({ id: String(r.id), email:String(r.email),name:String(r.name),role:r.role as Invitation['role'],expiresAt:Number(r.expires_at),createdAt:Number(r.created_at),state:String(r.state),invitedBy:String(r.invited_by ?? '') }));
   }

package/src/lib/email/templates.ts

@@ -12,6 +12,18 @@ export function accountMail(kind: 'invite'|'reset'|'welcome'|'password-changed'|
   return { to, subject: `${copy[0]} · ${site}`, text: [copy[0], '', copy[1], ...(url ? ['',`${copy[2]}: ${url}`] : [])].join('\n'),
     html: `<!doctype html><html><body style="margin:0;background:#f6f5f2;color:#24211c;font:16px/1.6 system-ui,sans-serif"><div style="max-width:520px;margin:auto;padding:32px 24px"><p style="color:#7d776e">${escape(site)}</p><h1 style="font-size:24px">${escape(copy[0])}</h1><p>${escape(copy[1])}</p>${url ? `<p><a style="display:inline-block;background:#ee5d20;color:#fff;padding:10px 18px;border-radius:8px;text-decoration:none" href="${escape(url)}">${escape(copy[2])}</a></p>` : ''}</div></body></html>` };
 }
+/** members' event requests (lib/calendar/requests.ts): to staff when one arrives, to the member when it's answered */
+export function eventRequestMail(kind: 'staff-new' | 'staff-changes' | 'approved' | 'declined', to: string, site: string, event: { title: string; when: string; by: string; note: string }, reply: string, url: string): Mail {
+  const copy = {
+    'staff-new': [`New event request: ${event.title}`, `${event.by || 'A member'} asked for “${event.title}” (${event.when}). It stays a draft until someone approves it.`, 'Review it'],
+    'staff-changes': [`Changes to review: ${event.title}`, `${event.by || 'A host'} suggested changes to “${event.title}” (${event.when}). The live event stays as it is until someone approves them.`, 'Review the changes'],
+    approved: [`Approved: ${event.title}`, `Your event “${event.title}” (${event.when}) was approved and is now on the calendar.`, 'See your events'],
+    declined: [`Not approved: ${event.title}`, `Your request for “${event.title}” (${event.when}) wasn’t approved.`, 'See your events'],
+  }[kind];
+  const extra = kind.startsWith('staff') ? (event.note ? `Their note: “${event.note}”` : '') : reply ? `From the team: “${reply}”` : '';
+  return { to, subject: `${copy[0]} · ${site}`, text: [copy[0], '', copy[1], ...(extra ? ['', extra] : []), '', `${copy[2]}: ${url}`].join('\n'),
+    html: `<!doctype html><html><body style="margin:0;background:#f6f5f2;color:#24211c;font:16px/1.6 system-ui,sans-serif"><div style="max-width:520px;margin:auto;padding:32px 24px"><p style="color:#7d776e">${escape(site)}</p><h1 style="font-size:22px">${escape(copy[0])}</h1><p>${escape(copy[1])}</p>${extra ? `<p style="background:#efebe4;border-radius:8px;padding:10px 12px">${escape(extra)}</p>` : ''}<p><a style="display:inline-block;background:#ee5d20;color:#fff;padding:10px 18px;border-radius:8px;text-decoration:none" href="${escape(url)}">${escape(copy[2])}</a></p></div></body></html>` };
+}
 /** a guest's app sign-in code; no link, so it works on any device */
 export function guestCodeMail(to: string, site: string, code: string): Mail {
   const intro = `Enter this code in the ${site} app to see your bookings. It expires in 10 minutes. If you did not ask for it, ignore this message.`;

package/src/lib/mobile/calendar.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { ContentRepository } from '../repo/types';
-import type { BookingLink, CalEvent, Calendar, Resource, Settings } from '../schema';
+import { publicTags, tagFilter, type BookingLink, type CalEvent, type Calendar, type Resource, type Settings } from '../schema';
 import { ApiError } from '../api';
 import { CALENDAR, bookingsEnabled, resourceUrl, bookingLinkUrl, publicEventFields } from '../calendar/config';
 import { calendarToJson, eventToJson } from '../calendar/api';
@@ -23,7 +23,9 @@ export async function listCalendars(repo: ContentRepository, url: URL) {
   const origin = siteOrigin(await repo.getSettings(), url);
   return { calendars: (await repo.listCalendars()).filter(c => c.visibility === 'public').map(c => calendarToJson(c, origin)) };
 }
-export const eventsQuery = z.object({ ...pageQuery, locale: localeQuery, from: isoDayOrInstant.optional(), to: isoDayOrInstant.optional(), calendar: z.string().min(1).max(200).optional(), q: z.string().max(100).optional() }).strict();
+// tag/excludeTag: a public tag's name or slug (internal "#" tags are never matched, as they are never shown)
+export const eventsQuery = z.object({ ...pageQuery, locale: localeQuery, from: isoDayOrInstant.optional(), to: isoDayOrInstant.optional(), calendar: z.string().min(1).max(200).optional(),
+  tag: z.string().min(1).max(100).optional(), excludeTag: z.string().min(1).max(100).optional(), q: z.string().max(100).optional() }).strict();
 export async function listEvents(repo: ContentRepository, url: URL) {
   requireCalendar();
   const q = eventsQuery.parse(queryParams(url));
@@ -44,7 +46,9 @@ export async function listEvents(repo: ContentRepository, url: URL) {
   const cal = q.calendar ? calendars.find(c => c.slug === q.calendar && c.visibility !== 'private') : null;
   if (q.calendar && !cal) throw new ApiError(404, 'Calendar not found.');
   const publicCalendars = new Map(calendars.filter(c => c.visibility === 'public' || c.id === cal?.id).map(c => [c.id, c]));
+  const tagged = tagFilter(q.tag, q.excludeTag);
   const visible = events.map(e => localizeDoc(e, locale ?? undefined)).filter(e => (cal ? e.calendarIds.includes(cal.id) && eventIsPublic(e, all) : eventIsListed(e, all))
+    && tagged(publicTags(e.tags))
     && (!term || indexed!.has(e.id) || `${e.title} ${e.excerpt} ${e.location.name}`.toLowerCase().includes(term.toLowerCase())));
   const occurrences = expandEvents(visible, settings, { displayTz: settings.timezone || 'UTC', now: Date.now(), windowStartMs: from, windowEndMs: to });
   occurrences.sort((a, b) => a.start - b.start || (a.event.id < b.event.id ? -1 : a.event.id > b.event.id ? 1 : 0));