Volunteer rosters: roles, sign-ups, swaps, QR check-in, kids-room duty (backend)

Serving roles per event or session, sign-ups and assigning with an overlap
check, swaps that happen on accept (notify recipients emailed), QR and manual
check-in (kids-room roles start rostered duty), optional free volunteer ticket,
day-before reminder job, hours served, privacy hooks. The kids check-in and
volunteer tickets are left out of public event pages and public registration.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-28 03:59:52 +02:00
co-authored by Claude Opus 5.5
parent a4fc2c0a88
commit a9f13a1b0a
16 changed files with 1494 additions and 7 deletions
@@ -0,0 +1,133 @@
-- CreateEnum
CREATE TYPE "VolunteerSwapStatus" AS ENUM ('open', 'accepted', 'cancelled');
-- AlterEnum
-- This migration adds more than one value to an enum.
-- With PostgreSQL versions 11 and earlier, this is not possible
-- in a single migration. This can be worked around by creating
-- multiple migrations, each migration adding only one value to
-- the enum.
ALTER TYPE "AdminAuditAction" ADD VALUE 'volunteer_settings_updated';
ALTER TYPE "AdminAuditAction" ADD VALUE 'volunteer_roles_changed';
ALTER TYPE "AdminAuditAction" ADD VALUE 'volunteer_assigned';
ALTER TYPE "AdminAuditAction" ADD VALUE 'volunteer_removed';
ALTER TYPE "AdminAuditAction" ADD VALUE 'volunteer_checked_in_manual';
-- AlterTable
ALTER TABLE "Event" ADD COLUMN "volunteerCheckInToken" TEXT,
ADD COLUMN "volunteerOptionId" TEXT;
-- AlterTable
ALTER TABLE "KidsRoomDuty" ADD COLUMN "fromRoster" BOOLEAN NOT NULL DEFAULT false;
-- CreateTable
CREATE TABLE "ServingRole" (
"id" TEXT NOT NULL,
"eventId" TEXT NOT NULL,
"sessionId" TEXT,
"name" TEXT NOT NULL,
"description" TEXT,
"needed" INTEGER NOT NULL DEFAULT 1,
"startsAt" TIMESTAMP(3),
"endsAt" TIMESTAMP(3),
"kidsRoomId" TEXT,
"order" INTEGER NOT NULL DEFAULT 0,
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
"updatedAt" TIMESTAMP(3) NOT NULL,
CONSTRAINT "ServingRole_pkey" PRIMARY KEY ("id")
);
-- CreateTable
CREATE TABLE "VolunteerSlot" (
"id" TEXT NOT NULL,
"roleId" TEXT NOT NULL,
"userId" TEXT NOT NULL,
"assignedById" TEXT,
"checkedInAt" TIMESTAMP(3),
"checkedInById" TEXT,
"checkInMethod" TEXT,
"remindedAt" TIMESTAMP(3),
"registrationId" TEXT,
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT "VolunteerSlot_pkey" PRIMARY KEY ("id")
);
-- CreateTable
CREATE TABLE "VolunteerSwap" (
"id" TEXT NOT NULL,
"slotId" TEXT,
"roleId" TEXT NOT NULL,
"fromUserId" TEXT,
"toUserId" TEXT,
"note" TEXT,
"status" "VolunteerSwapStatus" NOT NULL DEFAULT 'open',
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
"resolvedAt" TIMESTAMP(3),
CONSTRAINT "VolunteerSwap_pkey" PRIMARY KEY ("id")
);
-- CreateIndex
CREATE INDEX "ServingRole_eventId_sessionId_idx" ON "ServingRole"("eventId", "sessionId");
-- CreateIndex
CREATE INDEX "ServingRole_kidsRoomId_idx" ON "ServingRole"("kidsRoomId");
-- CreateIndex
CREATE INDEX "VolunteerSlot_userId_idx" ON "VolunteerSlot"("userId");
-- CreateIndex
CREATE INDEX "VolunteerSlot_registrationId_idx" ON "VolunteerSlot"("registrationId");
-- CreateIndex
CREATE UNIQUE INDEX "VolunteerSlot_roleId_userId_key" ON "VolunteerSlot"("roleId", "userId");
-- CreateIndex
CREATE INDEX "VolunteerSwap_roleId_status_idx" ON "VolunteerSwap"("roleId", "status");
-- CreateIndex
CREATE INDEX "VolunteerSwap_slotId_idx" ON "VolunteerSwap"("slotId");
-- CreateIndex
CREATE UNIQUE INDEX "Event_volunteerCheckInToken_key" ON "Event"("volunteerCheckInToken");
-- AddForeignKey
ALTER TABLE "ServingRole" ADD CONSTRAINT "ServingRole_eventId_fkey" FOREIGN KEY ("eventId") REFERENCES "Event"("id") ON DELETE CASCADE ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "ServingRole" ADD CONSTRAINT "ServingRole_sessionId_fkey" FOREIGN KEY ("sessionId") REFERENCES "EventSession"("id") ON DELETE CASCADE ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "ServingRole" ADD CONSTRAINT "ServingRole_kidsRoomId_fkey" FOREIGN KEY ("kidsRoomId") REFERENCES "AllocationGroup"("id") ON DELETE SET NULL ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "VolunteerSlot" ADD CONSTRAINT "VolunteerSlot_roleId_fkey" FOREIGN KEY ("roleId") REFERENCES "ServingRole"("id") ON DELETE CASCADE ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "VolunteerSlot" ADD CONSTRAINT "VolunteerSlot_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "VolunteerSlot" ADD CONSTRAINT "VolunteerSlot_assignedById_fkey" FOREIGN KEY ("assignedById") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "VolunteerSlot" ADD CONSTRAINT "VolunteerSlot_checkedInById_fkey" FOREIGN KEY ("checkedInById") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "VolunteerSlot" ADD CONSTRAINT "VolunteerSlot_registrationId_fkey" FOREIGN KEY ("registrationId") REFERENCES "Registration"("id") ON DELETE SET NULL ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "VolunteerSwap" ADD CONSTRAINT "VolunteerSwap_slotId_fkey" FOREIGN KEY ("slotId") REFERENCES "VolunteerSlot"("id") ON DELETE SET NULL ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "VolunteerSwap" ADD CONSTRAINT "VolunteerSwap_roleId_fkey" FOREIGN KEY ("roleId") REFERENCES "ServingRole"("id") ON DELETE CASCADE ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "VolunteerSwap" ADD CONSTRAINT "VolunteerSwap_fromUserId_fkey" FOREIGN KEY ("fromUserId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
-- AddForeignKey
ALTER TABLE "VolunteerSwap" ADD CONSTRAINT "VolunteerSwap_toUserId_fkey" FOREIGN KEY ("toUserId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+108
View File
@@ -158,6 +158,13 @@ model User {
kidsAlertsRaised KidsAlert[]
kidsRoomDuties KidsRoomDuty[]
// Volunteer rosters (1.46.0)
volunteerSlots VolunteerSlot[] @relation("VolunteerSlotUser")
volunteersAssigned VolunteerSlot[] @relation("VolunteerSlotAssignedBy")
volunteersCheckedIn VolunteerSlot[] @relation("VolunteerSlotCheckedInBy")
swapsAsked VolunteerSwap[] @relation("VolunteerSwapFrom")
swapsTaken VolunteerSwap[] @relation("VolunteerSwapTo")
@@index([homeCampusId])
}
@@ -304,6 +311,14 @@ model Event {
kidsCheckIns KidsCheckIn[]
kidsAlerts KidsAlert[]
// Volunteer rosters (1.46.0): serving roles for the event or one of its sessions. When
// `volunteerOptionId` is set (a main ticket of this event; off by default), each volunteer
// gets a free place on it. `volunteerCheckInToken` is in the check-in QR code volunteers scan
// on the day (made the first time the QR code is shown). Plain id, checked in utils/volunteers.js.
servingRoles ServingRole[]
volunteerOptionId String?
volunteerCheckInToken String? @unique
@@index([createdById])
@@index([closedById])
@@index([reopenedById])
@@ -399,6 +414,7 @@ model Registration {
bundleApplications RegistrationBundle[]
attendees Attendee[]
waitlistEntries WaitlistEntry[]
volunteerSlots VolunteerSlot[]
@@index([userId])
@@index([eventId])
@@ -678,6 +694,11 @@ enum AdminAuditAction {
kids_wrong_code
kids_custody_notes_changed
kids_offline_sync
volunteer_settings_updated
volunteer_roles_changed
volunteer_assigned
volunteer_removed
volunteer_checked_in_manual
}
// Append-only audit trail for admin/supervisor-initiated actions with money or
@@ -1364,6 +1385,7 @@ model AllocationGroup {
kidsCheckIns KidsCheckIn[]
kidsAlerts KidsAlert[]
kidsDuties KidsRoomDuty[]
servingRoles ServingRole[]
@@index([setId])
@@index([leaderUserId])
@@ -1639,6 +1661,7 @@ model EventSession {
reminders SessionReminderLog[]
registrationOptions RegistrationOption[]
waitlistEntries WaitlistEntry[]
servingRoles ServingRole[]
@@index([eventId, startsAt])
}
@@ -2017,9 +2040,94 @@ model KidsRoomDuty {
userId String
startedAt DateTime @default(now())
endedAt DateTime?
// Volunteer rosters (1.46.0): started by a rostered volunteer checking in, not "I'm on duty".
fromRoster Boolean @default(false)
room AllocationGroup @relation(fields: [roomId], references: [id], onDelete: Cascade)
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
@@index([roomId, occasion])
@@index([userId])
}
// ─── Volunteer rosters (1.46.0) ───────────────────────────────────────────────
// A serving role (Welcome, Parking, Sound…) for one event — or, on a multi-session event, one
// session — with the number of people needed. Shift times are optional (null = the session's or
// event's times). A role linked to a kids room puts its volunteers on duty there when they check
// in, so they count for the room's ratio.
model ServingRole {
id String @id @default(uuid())
eventId String
sessionId String?
name String
description String?
needed Int @default(1)
startsAt DateTime?
endsAt DateTime?
kidsRoomId String?
order Int @default(0)
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
event Event @relation(fields: [eventId], references: [id], onDelete: Cascade)
session EventSession? @relation(fields: [sessionId], references: [id], onDelete: Cascade)
kidsRoom AllocationGroup? @relation(fields: [kidsRoomId], references: [id], onDelete: SetNull)
slots VolunteerSlot[]
swaps VolunteerSwap[]
@@index([eventId, sessionId])
@@index([kidsRoomId])
}
// A person serving in a role. `assignedById` is the supervisor who put them there (null = they
// signed up). Withdrawing or being removed deletes the row; a swap moves it to the person who
// takes it over. `registrationId` is the free volunteer place they were given, if any.
model VolunteerSlot {
id String @id @default(uuid())
roleId String
userId String
assignedById String?
checkedInAt DateTime?
checkedInById String?
// 'qr' (the volunteer scanned the check-in QR code) or 'manual' (ticked by staff)
checkInMethod String?
remindedAt DateTime?
registrationId String?
createdAt DateTime @default(now())
role ServingRole @relation(fields: [roleId], references: [id], onDelete: Cascade)
user User @relation("VolunteerSlotUser", fields: [userId], references: [id], onDelete: Cascade)
assignedBy User? @relation("VolunteerSlotAssignedBy", fields: [assignedById], references: [id], onDelete: SetNull)
checkedInBy User? @relation("VolunteerSlotCheckedInBy", fields: [checkedInById], references: [id], onDelete: SetNull)
registration Registration? @relation(fields: [registrationId], references: [id], onDelete: SetNull)
swaps VolunteerSwap[]
@@unique([roleId, userId])
@@index([userId])
@@index([registrationId])
}
enum VolunteerSwapStatus {
open
accepted
cancelled
}
// "Can't make it": the volunteer asks someone to take their place. It happens as soon as someone
// accepts (the slot moves to them), and the event's notify recipients are told.
model VolunteerSwap {
id String @id @default(uuid())
slotId String?
roleId String
fromUserId String?
toUserId String?
note String?
status VolunteerSwapStatus @default(open)
createdAt DateTime @default(now())
resolvedAt DateTime?
slot VolunteerSlot? @relation(fields: [slotId], references: [id], onDelete: SetNull)
role ServingRole @relation(fields: [roleId], references: [id], onDelete: Cascade)
fromUser User? @relation("VolunteerSwapFrom", fields: [fromUserId], references: [id], onDelete: SetNull)
toUser User? @relation("VolunteerSwapTo", fields: [toUserId], references: [id], onDelete: SetNull)
@@index([roleId, status])
@@index([slotId])
}
@@ -8,6 +8,7 @@ const { assertEventOpen } = require('../utils/cashupUtils');
const { logAdminAction } = require('../utils/adminAudit');
const { getClientIp } = require('../utils/requestUtils');
const sessionsUtil = require('../utils/sessions');
const { publicOptions } = require('../utils/volunteers');
const { campusesEnabled, campusForEvent, campusWhere, resolveCampusFilter, EVENT_CAMPUS_SELECT } = require('../utils/campuses');
const { scopeFor, canView, canManage, eventWhere: scopeEventWhere, withScope } = require('../utils/campusScope');
@@ -374,7 +375,8 @@ const getEvents = async (req, res) => {
// Compute isSoldOut per event: true when every option that has a stock limit
// is fully sold out. Events with no limited options are never sold out.
const withStock = await Promise.all(events.map(async ev => {
const withStock = await Promise.all(events.map(async listed => {
const ev = { ...listed, eventOptions: publicOptions(listed) };
const earlyBirdEndsAt = earlyBirdEnds.get(ev.id) || null;
try {
// Picked-session options have per-session limits, so they never make the event sold out.
@@ -532,6 +534,8 @@ const getEventById = async (req, res) => {
if (!isStaffOrHigher) {
delete event.createdBy;
delete event.notifyRecipients;
// The kids check-in and volunteer tickets are handed out by staff, never sold.
event.eventOptions = publicOptions(event);
if (event.isActive === false) {
res.status(404);
throw new Error('Event not found');
@@ -13,6 +13,7 @@ const { findAccountByContact } = require('../utils/accountMatch');
const { ensureConsentRequests } = require('../utils/consent');
const { takenCount } = require('../utils/stock');
const { findOfferByToken, queueWaitlist } = require('../utils/waitlist');
const { reservedOptionIds } = require('../utils/volunteers');
// Youth events: send parental consent requests for any new under-18 attendees. Runs in
// the background so a slow mail/WhatsApp send never holds up the registration.
@@ -237,9 +238,11 @@ const createRegistration = async (req, res) => {
// Options are independent of each other, so resolve them concurrently. Errors are marked
// with `.isStockError` rather than relying on shared `res.statusCode` (which would race
// across concurrent iterations) — the outer catch always responds 400 regardless.
// The kids check-in and volunteer tickets are handed out by staff, never sold.
const reserved = new Set(isStaffRole(req.user?.role) ? [] : reservedOptionIds(event));
const resolvedOptions = await Promise.all(lines.map(async (option) => {
const eventOption = event.eventOptions.find(eo => eo.id === option.eventOptionId);
if (!eventOption) {
if (!eventOption || reserved.has(eventOption.id)) {
throw new Error(`Option with ID ${option.eventOptionId} not found for this event`);
}
if (!option.quantity || option.quantity < 1) {
@@ -1507,6 +1510,18 @@ const updateRegistrationOptions = async (req, res) => {
throw new Error("Sessions are booked by registering for them — they can't be changed here.");
}
}
// The kids check-in and volunteer tickets are handed out by staff: the owner can keep (or
// lower) the places they were given, not add more.
if (!isStaffRole(req.user.role)) {
for (const id of reservedOptionIds(registration.event)) {
const had = registration.registrationOptions.filter(ro => ro.eventOptionId === id).reduce((n, ro) => n + (ro.quantity || 0), 0);
const asked = options.filter(o => o.eventOptionId === id).reduce((n, o) => n + o.quantity, 0);
if (asked > had) {
res.status(400);
throw new Error('One or more options do not belong to this event');
}
}
}
// Picked-session lines aren't edited here: leave them exactly as they are (they still
// count towards the total due).
@@ -0,0 +1,269 @@
const prisma = require('../config/db');
const { safeErrorMessage } = require('../utils/errorUtils');
const { logAdminAction } = require('../utils/adminAudit');
const { getClientIp } = require('../utils/requestUtils');
const { logDataAccess } = require('../utils/accessLog');
const { listWhere, withScope } = require('../utils/campusScope');
const v = require('../utils/volunteers');
const fail = (res, error) => res.status(error.statusCode || 400).json({ message: safeErrorMessage(error), ...(error.code && typeof error.code === 'string' && !error.code.startsWith('P') ? { code: error.code } : {}) });
const audit = (req, action, targetType, targetId, metadata) => logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action, targetType, targetId, metadata, ip: getClientIp(req) });
const later = p => { Promise.resolve(p).catch(() => {}); };
const CONTACT = { id: true, name: true, email: true, phoneNumber: true, notificationPreference: true, isActive: true };
// ─── My account → Serving (anyone signed in) ──────────────────────────────────
// @desc My shifts, cover requests I could take, and events looking for volunteers
// @route GET /api/volunteers/me
const getMine = async (req, res) => {
try {
const now = new Date();
const [slots, cover, events] = await Promise.all([
v.mySlots({ userId: req.user.id, now }),
v.openSwaps({ userId: req.user.id, now }),
v.eventsWithRoles({ now, where: { isHidden: false, goLiveAt: { lte: now } } }),
]);
res.json({ slots, cover, events: events.map(e => ({ id: e.id, title: e.title, startDate: e.startDate, endDate: e.endDate, location: e.location, roles: e._count.servingRoles })) });
} catch (error) {
fail(res, error);
}
};
// @desc An event's serving roles: how full each is, and whether I'm in it
// @route GET /api/volunteers/events/:eventId
const getEventRoles = async (req, res) => {
try {
const out = await v.roster(req.params.eventId, { userId: req.user.id });
res.json(out);
} catch (error) {
fail(res, error);
}
};
// @route POST /api/volunteers/roles/:id/sign-up
const signUp = async (req, res) => {
try {
const { slot, role, event } = await v.signUp({ roleId: req.params.id, userId: req.user.id });
// req.user has no notification preference; the message goes the way they like it.
later(prisma.user.findUnique({ where: { id: req.user.id }, select: CONTACT }).then(user => v.signedUpMessages({ user, role, event })));
res.status(201).json({ slotId: slot.id, ticket: !!slot.registrationId });
} catch (error) {
fail(res, error);
}
};
// @desc Withdraw from a shift (the event's notify recipients are told)
// @route DELETE /api/volunteers/slots/:id
const withdraw = async (req, res) => {
try {
const out = await v.leave({ slotId: req.params.id, userId: req.user.id });
later(v.sendLeft(out));
res.json({ message: 'You\'re off the roster for this shift.' });
} catch (error) {
fail(res, error);
}
};
// @desc "Can't make it": ask the event's other volunteers to take over
// @route POST /api/volunteers/slots/:id/swap { note? }
const requestSwap = async (req, res) => {
try {
const out = await v.requestSwap({ slotId: req.params.id, userId: req.user.id, note: req.body?.note });
if (out.created) later(v.sendSwapRequest(out));
res.status(out.created ? 201 : 200).json({ swapId: out.swap.id });
} catch (error) {
fail(res, error);
}
};
// @route DELETE /api/volunteers/swaps/:id
const cancelSwap = async (req, res) => {
try {
res.json(await v.cancelSwap({ swapId: req.params.id, userId: req.user.id }));
} catch (error) {
fail(res, error);
}
};
// @desc Take over someone's place. Happens at once; the event's notify recipients are told.
// @route POST /api/volunteers/swaps/:id/accept
const acceptSwap = async (req, res) => {
try {
const out = await v.acceptSwap({ swapId: req.params.id, userId: req.user.id });
later(v.sendSwapAccepted(out));
res.json({ slotId: out.slot.id, role: out.slot.role.name, event: out.event.title });
} catch (error) {
fail(res, error);
}
};
// @desc Check in by scanning the event's volunteer QR code
// @route POST /api/volunteers/check-in { qr }
const checkIn = async (req, res) => {
try {
res.json(await v.checkInWithQr({ qr: req.body?.qr, userId: req.user.id }));
} catch (error) {
fail(res, error);
}
};
// ─── Staff: the roster on the day ─────────────────────────────────────────────
// @desc Events with serving roles (or upcoming, for supervisors setting them up)
// @route GET /api/volunteers/manage/events?all=1
const listEvents = async (req, res) => {
try {
const since = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
const base = req.query.all === '1' && ['admin', 'supervisor'].includes(req.user.role)
? { endDate: { gte: new Date(Date.now() - 24 * 60 * 60 * 1000) } }
: { endDate: { gte: since }, servingRoles: { some: {} } };
const events = await prisma.event.findMany({
where: withScope(base, await listWhere(req)),
select: { id: true, title: true, startDate: true, endDate: true, scheduleType: true, campusId: true, _count: { select: { servingRoles: true } } },
orderBy: { startDate: 'asc' },
take: 200,
});
res.json(events.map(e => ({ id: e.id, title: e.title, startDate: e.startDate, endDate: e.endDate, scheduleType: e.scheduleType, campusId: e.campusId, roles: e._count.servingRoles })));
} catch (error) {
fail(res, error);
}
};
// @desc The roster sheet: roles with their volunteers, contact details and check-ins
// @route GET /api/volunteers/manage/events/:eventId?log=1
const getRoster = async (req, res) => {
try {
const out = await v.roster(req.params.eventId, { staff: true, userId: req.user.id });
if (req.query.log === '1') {
logDataAccess(req, { action: 'volunteer_roster', eventId: out.event.id, records: out.roles.reduce((n, r) => n + r.volunteers.length, 0) });
}
res.json(out);
} catch (error) {
fail(res, error);
}
};
// @desc The check-in QR code volunteers scan on the day
// @route GET /api/volunteers/manage/events/:eventId/qr
const getQr = async (req, res) => {
try {
res.json(await v.checkInQr(req.params.eventId));
} catch (error) {
fail(res, error);
}
};
// @route POST /api/volunteers/manage/slots/:id/check-in { undo? }
const checkInManual = async (req, res) => {
try {
const out = await v.checkInManual({ slotId: req.params.id, staffUserId: req.user.id, undo: !!req.body?.undo });
if (out.changed) audit(req, 'volunteer_checked_in_manual', 'volunteer_slot', out.slot.id, { volunteer: out.slot.user.name, role: out.slot.role.name, undo: !!req.body?.undo });
res.json({ slotId: out.slot.id, changed: out.changed });
} catch (error) {
fail(res, error);
}
};
// ─── Supervisors: roles, people, settings, reports ────────────────────────────
// @route GET /api/volunteers/manage/events/:eventId/settings
const getSettings = async (req, res) => {
try {
res.json(await v.getSettings(req.params.eventId));
} catch (error) {
fail(res, error);
}
};
// @desc Free volunteer place on/off: { optionId } ('new' adds a free "Volunteer" ticket, null = off)
// @route PUT /api/volunteers/manage/events/:eventId/settings
const saveSettings = async (req, res) => {
try {
const out = await v.saveSettings(req.params.eventId, { optionId: req.body?.optionId ?? null });
audit(req, 'volunteer_settings_updated', 'event', out.event.id, { volunteerOptionId: out.event.volunteerOptionId });
res.json(out);
} catch (error) {
fail(res, error);
}
};
// @route POST /api/volunteers/manage/events/:eventId/roles { name, needed, sessionId?, startsAt?, endsAt?, description?, kidsRoomId? }
const createRole = async (req, res) => {
try {
const role = await v.createRole(req.params.eventId, req.body);
audit(req, 'volunteer_roles_changed', 'serving_role', role.id, { eventId: role.eventId, created: role.name, needed: role.needed });
res.status(201).json(role);
} catch (error) {
fail(res, error);
}
};
// @route PUT /api/volunteers/manage/roles/:id
const updateRole = async (req, res) => {
try {
const role = await v.updateRole(req.params.id, req.body);
audit(req, 'volunteer_roles_changed', 'serving_role', role.id, { eventId: role.eventId, updated: role.name, needed: role.needed });
res.json(role);
} catch (error) {
fail(res, error);
}
};
// @route DELETE /api/volunteers/manage/roles/:id (its volunteers are told)
const deleteRole = async (req, res) => {
try {
const out = await v.deleteRole(req.params.id);
audit(req, 'volunteer_roles_changed', 'serving_role', out.role.id, { eventId: out.role.eventId, deleted: out.role.name, volunteers: out.volunteers.length });
later(v.sendRoleDeleted(out));
res.json({ message: 'Deleted', volunteers: out.volunteers.length });
} catch (error) {
fail(res, error);
}
};
// @desc Put someone on a role (allowed beyond the number needed); they're told
// @route POST /api/volunteers/manage/roles/:id/assign { userId }
const assign = async (req, res) => {
try {
const user = await prisma.user.findUnique({ where: { id: String(req.body?.userId || '') }, select: CONTACT });
if (!user) throw v.volunteerError('Choose who to put on the roster.', 404);
const { slot, role, event } = await v.signUp({ roleId: req.params.id, userId: user.id, assignedById: req.user.id });
audit(req, 'volunteer_assigned', 'volunteer_slot', slot.id, { eventId: event.id, role: role.name, volunteer: user.name });
if (user.isActive) later(v.signedUpMessages({ user, role, event, by: req.user.name }));
res.status(201).json({ slotId: slot.id, ticket: !!slot.registrationId });
} catch (error) {
fail(res, error);
}
};
// @desc Take someone off a role (not after they've checked in); they're told
// @route DELETE /api/volunteers/manage/slots/:id
const remove = async (req, res) => {
try {
const out = await v.leave({ slotId: req.params.id });
audit(req, 'volunteer_removed', 'volunteer_slot', out.slot.id, { eventId: out.event.id, role: out.slot.role.name, volunteer: out.slot.user.name });
later(v.sendLeft({ ...out, byStaff: req.user.name }));
res.json({ message: 'Removed' });
} catch (error) {
fail(res, error);
}
};
// @desc Hours served per person (checked-in shifts), over the events the user can see
// @route GET /api/volunteers/manage/hours?eventId=&from=&to=
const hours = async (req, res) => {
try {
const scope = await listWhere(req);
const eventWhere = withScope(req.query.eventId ? { id: String(req.query.eventId) } : {}, scope);
const rows = await v.hoursServed({ eventWhere, from: req.query.from || null, to: req.query.to || null });
res.json(rows);
} catch (error) {
fail(res, error);
}
};
module.exports = {
getMine, getEventRoles, signUp, withdraw, requestSwap, cancelSwap, acceptSwap, checkIn,
listEvents, getRoster, getQr, checkInManual,
getSettings, saveSettings, createRole, updateRole, deleteRole, assign, remove, hours,
};
+4
View File
@@ -26,6 +26,10 @@ const BLOCKED = [
['POST', /^\/api\/waitlist\/?$/],
['POST', /^\/api\/coupons\/?$/],
['POST', /^\/api\/bundles\/event\/[^/]+\/?$/],
// Volunteer rosters: new roles and new people on them (they can carry a free ticket).
['POST', /^\/api\/volunteers\/roles\/[^/]+\/sign-up\/?$/],
['POST', /^\/api\/volunteers\/manage\/events\/[^/]+\/roles\/?$/],
['POST', /^\/api\/volunteers\/manage\/roles\/[^/]+\/assign\/?$/],
];
function isBlocked(method, path) {
+27
View File
@@ -184,6 +184,7 @@ app.get('/health', async (req, res) => {
app.use('/api/hub', require('./routes/hubRoutes'));
app.use('/api/campuses', require('./routes/campusRoutes'));
app.use('/api/kids', require('./routes/kidsRoutes'));
app.use('/api/volunteers', require('./routes/volunteerRoutes'));
app.use('/api/users', userRoutes);
app.use('/api/events', eventRoutes);
app.use('/api/registrations', registrationRoutes);
@@ -985,6 +986,32 @@ app.get('/docs', async (req, res) => {
{ method:'POST', path:'/api/kids/events/:eventId/sync', auth:'staff+', desc:'Sync an offline desk\'s check-ins and check-outs (idempotent by clientId). Audited as kids_offline_sync' },
]},
{ title: 'Volunteer rosters', base: '/api/volunteers', endpoints: [
{ method:'GET', path:'/api/volunteers/me', auth:'user', desc:'My shifts (upcoming and the last week), cover requests I could take, and events looking for volunteers' },
{ method:'GET', path:'/api/volunteers/events/:eventId', auth:'user', desc:'An event\'s serving roles: shift, how many are needed and signed up, whether I\'m in it, open cover requests' },
{ method:'POST', path:'/api/volunteers/roles/:id/sign-up', auth:'user', desc:'Sign up for a role. 409 ROLE_FULL when it\'s full, 409 SHIFT_CLASH when I serve elsewhere at the same time. Gives a free volunteer place when the event has one',
responses:[{ status:201, desc:'Signed up', body:{ slotId:'s_1', ticket:true } }] },
{ method:'DELETE', path:'/api/volunteers/slots/:id', auth:'user', desc:'Withdraw from a shift (not after checking in or once it\'s over). The event\'s notify recipients are emailed' },
{ method:'POST', path:'/api/volunteers/slots/:id/swap', auth:'user', desc:'"Can\'t make it": ask for cover. The event\'s other volunteers are told; the request shows on everyone\'s Serving page', request:{ body:{ note:'Away that weekend' } } },
{ method:'DELETE', path:'/api/volunteers/swaps/:id', auth:'user', desc:'Cancel my cover request' },
{ method:'POST', path:'/api/volunteers/swaps/:id/accept', auth:'user', desc:'Take over someone\'s place. Happens at once (409 SWAP_CLOSED if someone was first); both volunteers and the event\'s notify recipients are told' },
{ method:'POST', path:'/api/volunteers/check-in', auth:'user', desc:'Check in by scanning the event\'s volunteer QR code: every shift of mine on today is checked in; kids-room roles put me on duty in that room',
request:{ body:{ qr:'SERVE-3f2a…' } }, responses:[{ status:200, desc:'Checked in', body:{ event:{ id:'e_1', title:'Sunday service' }, checkedIn:[{ role:'Kids', kidsRoom:'Toddlers' }], already:[] } }] },
{ method:'GET', path:'/api/volunteers/manage/events', auth:'staff+', desc:'Events with serving roles from the last 30 days on (?all=1, supervisors: every upcoming event). Campus-scoped' },
{ method:'GET', path:'/api/volunteers/manage/events/:eventId', auth:'staff+', desc:'The roster sheet: roles with volunteers, contact details, check-ins and fill rate. ?log=1 writes the access log' },
{ method:'GET', path:'/api/volunteers/manage/events/:eventId/qr', auth:'staff+', desc:'The volunteer check-in QR code value for the event (made the first time)' },
{ method:'POST', path:'/api/volunteers/manage/slots/:id/check-in', auth:'staff+', desc:'Check a volunteer in by hand (undo:true to undo). Audited as volunteer_checked_in_manual' },
{ method:'GET', path:'/api/volunteers/manage/events/:eventId/settings', auth:'supervisor+', desc:'The volunteer ticket setting, the main tickets that can be it and the event\'s kids rooms' },
{ method:'PUT', path:'/api/volunteers/manage/events/:eventId/settings', auth:'supervisor+', desc:'Free volunteer place: optionId of a main ticket, "new" for a free "Volunteer" ticket, null for off (the default). Audited as volunteer_settings_updated', request:{ body:{ optionId:'new' } } },
{ method:'POST', path:'/api/volunteers/manage/events/:eventId/roles', auth:'supervisor+', desc:'Add a serving role (sessionId required on multi-session events; shift times optional). Audited as volunteer_roles_changed',
request:{ body:{ name:'Welcome', needed:4, sessionId:null, startsAt:'2026-11-08T07:30:00.000Z', endsAt:'2026-11-08T09:30:00.000Z', description:'Front doors', kidsRoomId:null } } },
{ method:'PUT', path:'/api/volunteers/manage/roles/:id', auth:'supervisor+', desc:'Change a role' },
{ method:'DELETE', path:'/api/volunteers/manage/roles/:id', auth:'supervisor+', desc:'Delete a role (refused once someone checked in for it); its volunteers are told' },
{ method:'POST', path:'/api/volunteers/manage/roles/:id/assign', auth:'supervisor+', desc:'Put someone on a role (allowed beyond the number needed); they\'re told. Audited as volunteer_assigned', request:{ body:{ userId:'u_1' } } },
{ method:'DELETE', path:'/api/volunteers/manage/slots/:id', auth:'supervisor+', desc:'Take someone off a role (not after check-in); they\'re told. Audited as volunteer_removed' },
{ method:'GET', path:'/api/volunteers/manage/hours?eventId=&from=&to=', auth:'supervisor+', desc:'Hours served per person (checked-in shifts × shift length), most first. Campus-scoped' },
]},
{ title: 'Privacy (POPIA)', base: '/api/privacy', endpoints: [
{ method:'GET', path:'/api/privacy/me', auth:'user', desc:'My news opt-in, its history, and my privacy requests',
responses:[{ status:200, desc:'Success', body:{ news:{ email:true, whatsapp:false }, newsAskedAt:'2026-10-23T08:00:00.000Z', canWhatsApp:false, notificationPreference:'email', history:[{ channel:'email', granted:true, source:'signup', createdAt:'2026-10-23T08:00:00.000Z' }], requests:[] }}]},
+4
View File
@@ -45,6 +45,10 @@ const JOBS = [
return { reminders, certificates };
},
},
{
name: 'volunteers', label: 'Volunteer reminders the day before a shift', cron: '*/15 * * * *', env: 'VOLUNTEER_JOBS_ENABLED',
run: () => require('../utils/volunteers').runReminderJob(),
},
{
name: 'consent', label: 'Parental consent reminders and medical-detail deletion', cron: '0 9 * * *', env: 'CONSENT_JOBS_ENABLED',
run: async () => {
@@ -0,0 +1,33 @@
const express = require('express');
const router = express.Router();
const c = require('../controllers/volunteerController');
const { protect, staff, supervisor } = require('../middleware/authMiddleware');
const { scopeEvent, scopeList } = require('../utils/campusScope');
// My account → Serving (anyone with an account can volunteer; only their own slots)
router.get('/me', protect, c.getMine);
router.get('/events/:eventId', protect, c.getEventRoles);
router.post('/roles/:id/sign-up', protect, c.signUp);
router.delete('/slots/:id', protect, c.withdraw);
router.post('/slots/:id/swap', protect, c.requestSwap);
router.delete('/swaps/:id', protect, c.cancelSwap);
router.post('/swaps/:id/accept', protect, c.acceptSwap);
router.post('/check-in', protect, c.checkIn);
// The roster on the day (staff)
router.get('/manage/events', protect, staff, scopeList, c.listEvents);
router.get('/manage/events/:eventId', protect, staff, scopeEvent(), c.getRoster);
router.get('/manage/events/:eventId/qr', protect, staff, scopeEvent(), c.getQr);
router.post('/manage/slots/:id/check-in', protect, staff, scopeEvent({ resolve: 'volunteerSlot' }), c.checkInManual);
// Roles, people, settings and reports (supervisors)
router.get('/manage/events/:eventId/settings', protect, supervisor, scopeEvent(), c.getSettings);
router.put('/manage/events/:eventId/settings', protect, supervisor, scopeEvent({ need: 'manage' }), c.saveSettings);
router.post('/manage/events/:eventId/roles', protect, supervisor, scopeEvent({ need: 'manage' }), c.createRole);
router.put('/manage/roles/:id', protect, supervisor, scopeEvent({ resolve: 'servingRole', need: 'manage' }), c.updateRole);
router.delete('/manage/roles/:id', protect, supervisor, scopeEvent({ resolve: 'servingRole', need: 'manage' }), c.deleteRole);
router.post('/manage/roles/:id/assign', protect, supervisor, scopeEvent({ resolve: 'servingRole' }), c.assign);
router.delete('/manage/slots/:id', protect, supervisor, scopeEvent({ resolve: 'volunteerSlot' }), c.remove);
router.get('/manage/hours', protect, supervisor, scopeList, c.hours);
module.exports = router;
@@ -17,6 +17,7 @@ const ACCESS_ACTIONS = {
impersonation: 'Viewed the site as another user',
kids_rooms: 'Kids check-in desk or room opened',
kids_offline: 'Kids check-in list downloaded for offline use',
volunteer_roster: 'Volunteer roster opened',
};
/**
@@ -104,6 +104,8 @@ const RESOLVERS = {
},
kidsCheckIn: async id => shape((await prisma.kidsCheckIn.findUnique({ where: { id }, select: { event: EV } }))?.event),
kidsAlert: async id => shape((await prisma.kidsAlert.findUnique({ where: { id }, select: { event: EV } }))?.event),
servingRole: async id => shape((await prisma.servingRole.findUnique({ where: { id }, select: { event: EV } }))?.event),
volunteerSlot: async id => shape((await prisma.volunteerSlot.findUnique({ where: { id }, select: { role: { select: { event: EV } } } }))?.role?.event),
};
/** The event a record belongs to (see RESOLVERS), or null. */
+6 -3
View File
@@ -584,7 +584,7 @@ async function pageParent({ checkInId, message, staffUserId }, db = prisma) {
async function board({ eventId, sessionId = null, now = new Date() }, db = prisma) {
const event = await loadKidsEvent(eventId, db);
const { occasion, sessionId: sid } = occasionFor(event, event.sessions, sessionId, now);
const [rooms, checkIns, duties, alerts] = await Promise.all([
const [rooms, checkIns, duties, alerts, rostered] = await Promise.all([
roomsFor(event, db),
db.kidsCheckIn.findMany({
where: { eventId: event.id, occasion },
@@ -598,6 +598,9 @@ async function board({ eventId, sessionId = null, now = new Date() }, db = prism
}),
db.kidsRoomDuty.findMany({ where: { occasion, endedAt: null, room: { setId: event.kidsRoomSetId } }, include: { user: { select: { id: true, name: true } } } }),
db.kidsAlert.findMany({ where: { eventId: event.id, occasion }, orderBy: { createdAt: 'desc' }, take: 50, include: { createdBy: { select: { name: true } } } }),
// Volunteer rosters (1.46.0): who is rostered in each room. They count as leaders on duty
// once they check in (a KidsRoomDuty with fromRoster), like "I'm on duty".
require('./volunteers').rosteredForRooms(event, occasion, db),
]);
const familyIds = [...new Set(checkIns.map(c => c.pickupCode.familyId).filter(Boolean))];
const families = familyIds.length ? await db.family.findMany({ where: { id: { in: familyIds } }, include: FAMILY_INCLUDE }) : [];
@@ -614,7 +617,7 @@ async function board({ eventId, sessionId = null, now = new Date() }, db = prism
sessionLabel,
rooms: rooms.map(r => {
const leaders = duties.filter(d => d.roomId === r.id).map(d => d.user);
return { id: r.id, name: r.name, minAge: r.minAge, maxAge: r.maxAge, capacity: r.capacity, ratio: r.ratio, order: r.order, leaderNames: leaders.map(l => l.name), leaderIds: leaders.map(l => l.id), ...roomStatus(r, inByRoom[r.id] || 0, leaders.length) };
return { id: r.id, name: r.name, minAge: r.minAge, maxAge: r.maxAge, capacity: r.capacity, ratio: r.ratio, order: r.order, leaderNames: leaders.map(l => l.name), leaderIds: leaders.map(l => l.id), rostered: rostered[r.id] || [], ...roomStatus(r, inByRoom[r.id] || 0, leaders.length) };
}),
checkIns: checkIns.map(c => {
const fam = famById[c.pickupCode.familyId];
@@ -835,7 +838,7 @@ module.exports = {
randomCode, normaliseCode, ageOn, fitsRoom, suggestRoom, roomStatus, stickerAlert, occasionFor, checkInMessage, listNames,
childView, familyView, loadFamily, familyOfUser, createFamily, cleanChild, cleanAdult, custodyChanged, searchFamilies,
loadKidsEvent, roomsFor, getSettings, saveSettings,
codeForFamily, reserveCodes, checkIn, checkOut, overrideCheckOut, sendCheckInMessages, pageParent,
codeForFamily, reserveCodes, checkIn, checkOut, overrideCheckOut, messageParent, sendCheckInMessages, pageParent,
board, setDuty, moveRoom, activeForFamily, offlineSnapshot, syncOffline,
removeFromFamily, exportFamily, runKidsRetention, previewKidsRetention,
};
@@ -1513,6 +1513,7 @@ async function sendAttendeeFormLinkMessage(attendee) {
}
module.exports = {
getEventNotifyEmails,
buildEventNotifyRecipientList,
sendAttendeeFormLinkMessage,
sendRegistrationEmails,
+11 -2
View File
@@ -460,7 +460,10 @@ async function anonymiseUser(userId, db = prisma) {
const { familyDeleted } = await require('./kids').removeFromFamily(tx, userId);
await tx.kidsCheckIn.updateMany({ where: { checkedOutById: userId }, data: { checkedOutById: null } });
return { attendees: attendeeIds.length, formAnswers: answers.count, providerRecords: txns.length + checkouts.length, familyDeleted };
// Volunteer rosters: shifts still to come are given up; past ones stay for hours served.
const shiftsGivenUp = await require('./volunteers').forgetVolunteer(tx, userId);
return { attendees: attendeeIds.length, formAnswers: answers.count, providerRecords: txns.length + checkouts.length, familyDeleted, shiftsGivenUp };
});
await clearTrustedDevices(userId);
@@ -482,7 +485,7 @@ async function exportUserData(userId, db = prisma) {
});
if (!user) return null;
const [registrations, payments, tickets, waitlist, certificates, feedback, consents, security, requests, notices, family] = await Promise.all([
const [registrations, payments, tickets, waitlist, certificates, feedback, consents, security, requests, notices, family, volunteering] = await Promise.all([
db.registration.findMany({
where: { userId },
orderBy: { createdAt: 'asc' },
@@ -507,6 +510,7 @@ async function exportUserData(userId, db = prisma) {
db.dataRequest.findMany({ where: { userId }, orderBy: { createdAt: 'desc' }, select: { type: true, status: true, details: true, response: true, createdAt: true, closedAt: true } }),
db.noticeAcceptance.findMany({ where: { userId }, orderBy: { createdAt: 'desc' }, select: { version: true, source: true, createdAt: true } }),
require('./kids').exportFamily(userId, db),
require('./volunteers').exportVolunteering(userId, db),
]);
return {
@@ -549,6 +553,7 @@ async function exportUserData(userId, db = prisma) {
accountActivity: security.map(s => ({ type: s.type, ip: s.ip, device: s.device, at: s.createdAt })),
dataRequests: requests,
kidsFamily: family,
volunteering,
};
}
@@ -605,6 +610,10 @@ async function dataExportPdf(data) {
heading('Certificates');
for (const c of data.certificates) para(`${c.event} — ${c.code}${c.revoked ? ' (withdrawn)' : ''}`);
}
if (data.volunteering?.length) {
heading('Serving (volunteer rosters)');
for (const s of data.volunteering) para(`${fmt(s.from)} — ${s.role}, ${s.event}${s.checkedIn ? ' (checked in)' : ''}`);
}
if (data.feedback.length) {
heading('Feedback you gave');
for (const f of data.feedback) {
+782
View File
@@ -0,0 +1,782 @@
/**
* Volunteer rosters (1.46.0). Who serves where at an event:
*
* - Serving roles (Welcome, Parking, Kids, Sound…) belong to one event, or — on a multi-session
* event — to one session, with the number of people needed and optional shift times (default:
* the session's or event's times). Rosters never repeat: each event/session has its own roles.
* - Anyone with an account can sign up for a role that isn't full; supervisors can also assign
* people (even beyond the number needed). Nobody can be in two roles whose shifts overlap.
* - Volunteers get a reminder the day before their shift. "Can't make it" asks for cover: the
* request shows on the Serving page and goes to the event's other volunteers, and the place
* moves as soon as someone accepts — the event's notify recipients are told, nobody approves.
* - On the day volunteers check themselves in by scanning the event's volunteer QR code (or staff
* tick them in). A role linked to a kids room puts its volunteers on duty in that room when they
* check in, so they count for the room's leader-to-children ratio.
* - A free volunteer place on a ticket of the event is off by default; a supervisor turns it on
* per event by choosing the ticket. Volunteers who already have a ticket keep theirs.
*/
const crypto = require('crypto');
const { v4: uuidv4 } = require('uuid');
const prisma = require('../config/db');
const sessionsUtil = require('./sessions');
const MAX_NEEDED = 200;
const MAX_ROLES = 100;
const HOUR = 60 * 60 * 1000;
// Reminders go out this long before a shift, to people who signed up before then.
const REMIND_BEFORE_MS = 24 * HOUR;
// What the check-in QR code holds: the prefix, then the event's token.
const QR_PREFIX = 'SERVE-';
function volunteerError(message, statusCode = 400, code = undefined) {
return Object.assign(new Error(message), { statusCode, ...(code ? { code } : {}) });
}
// ─── Pure helpers ─────────────────────────────────────────────────────────────
/** A role's shift: its own times, else its session's, else the event's. */
function shiftOf(role, event) {
const session = role.session || (role.sessionId ? (event.sessions || []).find(s => s.id === role.sessionId) : null);
return {
startsAt: new Date(role.startsAt || session?.startsAt || event.startDate),
endsAt: new Date(role.endsAt || session?.endsAt || event.endDate),
};
}
/** Whether two shifts overlap (touching ends don't count: 08:00–10:00 and 10:00–12:00 are fine). */
function overlaps(a, b) {
return new Date(a.startsAt) < new Date(b.endsAt) && new Date(b.startsAt) < new Date(a.endsAt);
}
/** Hours in a shift, to the nearest quarter hour. */
function shiftHours(shift) {
const h = (new Date(shift.endsAt) - new Date(shift.startsAt)) / HOUR;
return h > 0 ? Math.round(h * 4) / 4 : 0;
}
/** { needed, filled, open, full } for a role with `filled` volunteers. */
function fillOf(needed, filled) {
return { needed, filled, open: Math.max(0, needed - filled), full: filled >= needed };
}
/** Volunteers can check in on the day(s) of their shift, until it ends. */
function checkInOpen(shift, now = new Date()) {
const today = sessionsUtil.dayKey(now);
return today >= sessionsUtil.dayKey(shift.startsAt) && today <= sessionsUtil.dayKey(shift.endsAt) && new Date(now) <= new Date(shift.endsAt);
}
/**
* Whether a slot's reminder is due: not sent yet, the shift starts within the next 24 hours, and
* the person signed up more than half an hour ago (someone who just signed up doesn't need one).
*/
function reminderDue({ remindedAt, createdAt }, shift, now = new Date()) {
if (remindedAt) return false;
const t = new Date(now).getTime();
const start = new Date(shift.startsAt).getTime();
return start > t && start - t <= REMIND_BEFORE_MS && t - new Date(createdAt).getTime() > HOUR / 2;
}
/** The kids room occasion a check-in counts for (see utils/kids.js occasionFor): the session, or today. */
function kidsOccasion(role, now = new Date()) {
return role.sessionId || sessionsUtil.dayKey(now);
}
/** Ticket options only staff hand out — the kids check-in and volunteer tickets — never sold publicly. */
function reservedOptionIds(event) {
return [event?.kidsOptionId, event?.volunteerOptionId].filter(Boolean);
}
/** The event's options without the reserved ones (for public event pages and lists). */
function publicOptions(event) {
const reserved = new Set(reservedOptionIds(event));
return (event?.eventOptions || []).filter(o => !reserved.has(o.id));
}
function fmtWhen(d) {
return new Date(d).toLocaleString('en-GB', { timeZone: sessionsUtil.TIMEZONE, weekday: 'short', day: 'numeric', month: 'short', hour: '2-digit', minute: '2-digit' });
}
function fmtTime(d) {
return new Date(d).toLocaleTimeString('en-GB', { timeZone: sessionsUtil.TIMEZONE, hour: '2-digit', minute: '2-digit' });
}
/** "Sat 7 Nov, 08:00–10:30" (the end date is added when the shift runs past midnight). */
function shiftText(shift) {
const sameDay = sessionsUtil.dayKey(shift.startsAt) === sessionsUtil.dayKey(shift.endsAt);
return `${fmtWhen(shift.startsAt)}–${sameDay ? fmtTime(shift.endsAt) : fmtWhen(shift.endsAt)}`;
}
function cleanText(v, max) {
return String(v ?? '').trim().slice(0, max);
}
// ─── Loading ──────────────────────────────────────────────────────────────────
const EVENT_SELECT = {
id: true, title: true, startDate: true, endDate: true, scheduleType: true, isActive: true, location: true, campusId: true,
kidsCheckIn: true, kidsRoomSetId: true, kidsOptionId: true, volunteerOptionId: true, volunteerCheckInToken: true,
sessions: { orderBy: { startsAt: 'asc' } },
};
async function loadEvent(eventId, db = prisma) {
const event = await db.event.findUnique({ where: { id: String(eventId || '') }, select: EVENT_SELECT });
if (!event) throw volunteerError('Event not found', 404);
return event;
}
const USER_SELECT = { id: true, name: true, email: true, phoneNumber: true, notificationPreference: true };
const ROLE_INCLUDE = {
session: true,
kidsRoom: { select: { id: true, name: true } },
slots: {
orderBy: { createdAt: 'asc' },
include: { user: { select: USER_SELECT }, assignedBy: { select: { name: true } }, checkedInBy: { select: { name: true } } },
},
swaps: { where: { status: 'open' }, orderBy: { createdAt: 'asc' } },
};
const realEmail = e => (e && !/@(guest\.local|deleted\.invalid|deleted\.local)$/.test(e) ? e : null);
/**
* A role for the API. `staff` adds the volunteers (names, contact, check-ins); others see only
* how full it is, whether they're in it, and open cover requests.
*/
function roleView(role, event, { staff = false, userId = null, now = new Date() } = {}) {
const shift = shiftOf(role, event);
const sessions = sessionsUtil.activeSessions(event.sessions);
const mine = userId ? role.slots.find(s => s.userId === userId) : null;
const swapBySlot = Object.fromEntries(role.swaps.map(w => [w.slotId, w]));
return {
id: role.id,
eventId: role.eventId,
sessionId: role.sessionId,
sessionLabel: role.session ? sessionsUtil.sessionLabel(role.session, sessions) : null,
name: role.name,
description: role.description || '',
startsAt: role.startsAt,
endsAt: role.endsAt,
shift: { startsAt: shift.startsAt, endsAt: shift.endsAt, text: shiftText(shift), hours: shiftHours(shift) },
kidsRoom: role.kidsRoom || null,
order: role.order,
past: new Date(shift.endsAt) < new Date(now),
...fillOf(role.needed, role.slots.length),
mine: mine ? { slotId: mine.id, checkedInAt: mine.checkedInAt, swapId: swapBySlot[mine.id]?.id || null } : null,
coverNeeded: role.swaps.filter(w => w.fromUserId !== userId).map(w => ({ swapId: w.id, note: w.note || '' })),
...(staff ? {
volunteers: role.slots.map(s => ({
slotId: s.id,
userId: s.user.id,
name: s.user.name,
phone: s.user.phoneNumber || null,
email: realEmail(s.user.email),
assignedBy: s.assignedBy?.name || null,
checkedInAt: s.checkedInAt,
checkedInBy: s.checkedInBy?.name || null,
checkInMethod: s.checkInMethod,
swapOpen: !!swapBySlot[s.id],
hasTicket: !!s.registrationId,
})),
} : {}),
};
}
/** An event's roster: its roles in order (by session, then shift start, then order). */
async function roster(eventId, { staff = false, userId = null, now = new Date() } = {}, db = prisma) {
const event = await loadEvent(eventId, db);
const roles = await db.servingRole.findMany({ where: { eventId: event.id }, include: ROLE_INCLUDE });
const views = roles.map(r => roleView(r, event, { staff, userId, now }))
.sort((a, b) => new Date(a.shift.startsAt) - new Date(b.shift.startsAt) || a.order - b.order || a.name.localeCompare(b.name));
const totals = views.reduce((t, r) => ({ needed: t.needed + r.needed, filled: t.filled + Math.min(r.filled, r.needed), checkedIn: t.checkedIn + (r.volunteers || []).filter(v => v.checkedInAt).length }), { needed: 0, filled: 0, checkedIn: 0 });
return {
event: { id: event.id, title: event.title, startDate: event.startDate, endDate: event.endDate, scheduleType: event.scheduleType, location: event.location, kidsCheckIn: event.kidsCheckIn },
sessions: sessionsUtil.activeSessions(event.sessions).map(s => ({ id: s.id, label: sessionsUtil.sessionLabel(s, event.sessions), startsAt: s.startsAt, endsAt: s.endsAt })),
roles: views,
totals: { ...totals, fillRate: totals.needed ? Math.round((totals.filled / totals.needed) * 100) : null },
};
}
// ─── Roles (supervisors) ──────────────────────────────────────────────────────
function parseTime(v, what) {
if (v === undefined) return undefined;
if (v === null || v === '') return null;
const d = new Date(v);
if (Number.isNaN(d.getTime())) throw volunteerError(`Enter a valid ${what}.`);
return d;
}
/** Check and clean a role from the request (`existing` when changing one). */
async function cleanRole(event, input, existing = null, db = prisma) {
const b = input || {};
const data = {};
if (b.name !== undefined || !existing) {
data.name = cleanText(b.name, 60);
if (!data.name) throw volunteerError('Enter a name for the role (e.g. Welcome, Parking, Sound).');
}
if (b.description !== undefined) data.description = cleanText(b.description, 500) || null;
if (b.needed !== undefined || !existing) {
const n = parseInt(b.needed ?? 1, 10);
if (!Number.isFinite(n) || n < 1 || n > MAX_NEEDED) throw volunteerError(`The number of people needed must be from 1 to ${MAX_NEEDED}.`);
data.needed = n;
}
if (b.sessionId !== undefined || !existing) {
if (event.scheduleType === 'sessions') {
const session = event.sessions.find(s => s.id === b.sessionId && !s.cancelledAt);
if (!session) throw volunteerError('Choose the session this role is for.');
data.sessionId = session.id;
} else data.sessionId = null;
}
const startsAt = parseTime(b.startsAt, 'start time');
const endsAt = parseTime(b.endsAt, 'end time');
if (startsAt !== undefined) data.startsAt = startsAt;
if (endsAt !== undefined) data.endsAt = endsAt;
const shift = shiftOf({ ...existing, ...data, session: undefined }, event);
if (shift.endsAt <= shift.startsAt) throw volunteerError('The shift has to end after it starts.');
if (b.kidsRoomId !== undefined) {
if (!b.kidsRoomId) data.kidsRoomId = null;
else {
const room = event.kidsRoomSetId ? await db.allocationGroup.findFirst({ where: { id: String(b.kidsRoomId), setId: event.kidsRoomSetId } }) : null;
if (!room) throw volunteerError('Choose one of this event\'s kids rooms (set up under Kids check-in setup).');
data.kidsRoomId = room.id;
}
}
if (b.order !== undefined) data.order = Math.max(0, Math.min(1000, parseInt(b.order, 10) || 0));
return data;
}
async function createRole(eventId, input, db = prisma) {
const event = await loadEvent(eventId, db);
if (await db.servingRole.count({ where: { eventId: event.id } }) >= MAX_ROLES) throw volunteerError(`An event can have up to ${MAX_ROLES} serving roles.`);
const data = await cleanRole(event, input, null, db);
if (input?.order === undefined) data.order = await db.servingRole.count({ where: { eventId: event.id, sessionId: data.sessionId } });
return db.servingRole.create({ data: { ...data, eventId: event.id } });
}
async function updateRole(roleId, input, db = prisma) {
const existing = await db.servingRole.findUnique({ where: { id: String(roleId || '') } });
if (!existing) throw volunteerError('Role not found', 404);
const event = await loadEvent(existing.eventId, db);
const data = await cleanRole(event, input, existing, db);
if (data.sessionId !== undefined && data.sessionId !== existing.sessionId && await db.volunteerSlot.count({ where: { roleId: existing.id } })) {
throw volunteerError('People have signed up for this role, so it can\'t move to another session — add a new role there instead.');
}
return db.servingRole.update({ where: { id: existing.id }, data });
}
/**
* Delete a role. Refused once someone has checked in for it (it counts for hours served).
* Returns the volunteers who were on it, so they can be told.
*/
async function deleteRole(roleId, db = prisma) {
const role = await db.servingRole.findUnique({ where: { id: String(roleId || '') }, include: { slots: { include: { user: { select: USER_SELECT } } } } });
if (!role) throw volunteerError('Role not found', 404);
if (role.slots.some(s => s.checkedInAt)) throw volunteerError('Someone has already checked in for this role, so it stays on the roster (it counts for hours served).');
const event = await loadEvent(role.eventId, db);
await db.$transaction(async tx => {
for (const s of role.slots) await releasePlace(tx, s);
await tx.servingRole.delete({ where: { id: role.id } });
});
return { role, event, volunteers: role.slots.map(s => s.user) };
}
// ─── Settings ─────────────────────────────────────────────────────────────────
/** The event's volunteer settings and the tickets that can be the volunteer ticket. */
async function getSettings(eventId, db = prisma) {
const event = await loadEvent(eventId, db);
const [options, rooms] = await Promise.all([
db.eventOption.findMany({ where: { eventId: event.id, isMainTicket: true, sessionMode: 'all' }, select: { id: true, name: true, price: true }, orderBy: { name: 'asc' } }),
event.kidsRoomSetId ? db.allocationGroup.findMany({ where: { setId: event.kidsRoomSetId }, select: { id: true, name: true }, orderBy: { order: 'asc' } }) : [],
]);
return {
event: { id: event.id, title: event.title, volunteerOptionId: event.volunteerOptionId },
options: options.filter(o => o.id !== event.kidsOptionId),
kidsRooms: rooms,
};
}
/**
* Turn the free volunteer place on or off. `optionId: 'new'` adds a free "Volunteer" main ticket
* (staff-only: it never shows publicly); null switches it off (places already given stay).
*/
async function saveSettings(eventId, { optionId }, db = prisma) {
const event = await loadEvent(eventId, db);
let next = null;
if (optionId === 'new') {
next = (await db.eventOption.create({ data: { eventId: event.id, name: 'Volunteer', price: 0, isMainTicket: true, sessionMode: 'all' } })).id;
} else if (optionId) {
const opt = await db.eventOption.findFirst({ where: { id: String(optionId), eventId: event.id, isMainTicket: true, sessionMode: 'all' } });
if (!opt || opt.id === event.kidsOptionId) throw volunteerError('Choose a main ticket of this event that covers the whole event (not the kids ticket).');
next = opt.id;
}
await db.event.update({ where: { id: event.id }, data: { volunteerOptionId: next } });
return getSettings(event.id, db);
}
/** The event's check-in QR value (the token is made the first time). */
async function checkInQr(eventId, db = prisma) {
const event = await loadEvent(eventId, db);
let token = event.volunteerCheckInToken;
if (!token) {
token = crypto.randomBytes(12).toString('hex');
await db.event.update({ where: { id: event.id }, data: { volunteerCheckInToken: token } });
}
return { token, qr: QR_PREFIX + token };
}
// ─── The free volunteer place ─────────────────────────────────────────────────
/**
* Give a volunteer a free place on the event's volunteer ticket, when that's switched on and they
* have no ticket for the event yet. Returns the registration id (shared by their slots), or null.
*/
async function givePlace(tx, event, userId) {
if (!event.volunteerOptionId) return null;
const shared = await tx.volunteerSlot.findFirst({ where: { userId, registrationId: { not: null }, role: { eventId: event.id }, registration: { status: { not: 'cancelled' } } }, select: { registrationId: true } });
if (shared) return shared.registrationId;
const hasTicket = await tx.ticket.count({ where: { eventId: event.id, OR: [{ userId }, { holderUserId: userId }], registrationOption: { registration: { status: { not: 'cancelled' } } } } });
if (hasTicket) return null;
const registration = await tx.registration.create({ data: { userId, eventId: event.id, status: 'paid' } });
const line = await tx.registrationOption.create({ data: { registrationId: registration.id, eventOptionId: event.volunteerOptionId, quantity: 1, priceSnapshot: 0 } });
await tx.registrationOptionTranche.create({ data: { registrationOptionId: line.id, quantity: 1, priceSnapshot: 0 } });
await tx.ticket.create({ data: { id: uuidv4(), qrCode: uuidv4(), registrationOptionId: line.id, userId, eventId: event.id, quantity: 1, emailSent: true } });
return registration.id;
}
/**
* When a slot goes (withdrawn, removed, swapped away): cancel its free place if no other slot of
* the person at the event still uses it and the ticket was never scanned.
*/
async function releasePlace(tx, slot) {
if (!slot.registrationId) return;
const others = await tx.volunteerSlot.count({ where: { registrationId: slot.registrationId, id: { not: slot.id }, userId: slot.userId } });
if (others) return;
const scanned = await tx.ticketUsage.count({ where: { ticket: { registrationOption: { registrationId: slot.registrationId } } } });
if (scanned) return;
await tx.registration.updateMany({ where: { id: slot.registrationId, status: { not: 'cancelled' } }, data: { status: 'cancelled' } });
}
// ─── Signing up ───────────────────────────────────────────────────────────────
async function loadRole(roleId, db = prisma) {
const role = await db.servingRole.findUnique({ where: { id: String(roleId || '') }, include: { session: true, slots: { select: { id: true, userId: true } } } });
if (!role) throw volunteerError('Role not found', 404);
return role;
}
/** Refuse a role whose shift is over, a cancelled session, or an inactive event. */
function assertOpen(role, event, now = new Date()) {
if (!event.isActive) throw volunteerError('This event isn\'t open any more.');
if (role.session?.cancelledAt) throw volunteerError('That session was cancelled.');
if (shiftOf(role, event).endsAt <= new Date(now)) throw volunteerError('This shift is already over.');
}
/** Refuse when the person serves in another role at the same time. */
async function assertFree(tx, event, role, userId) {
const shift = shiftOf(role, event);
const theirs = await tx.volunteerSlot.findMany({ where: { userId, roleId: { not: role.id }, role: { eventId: event.id } }, include: { role: { include: { session: true } } } });
const clash = theirs.find(s => overlaps(shiftOf(s.role, event), shift));
if (clash) throw volunteerError(`${clash.role.name} (${shiftText(shiftOf(clash.role, event))}) is at the same time.`, 409, 'SHIFT_CLASH');
}
/**
* Put someone on a role: they signed up (`assignedById` null — refused when the role is full), or
* a supervisor assigned them (allowed beyond the number needed).
*/
async function signUp({ roleId, userId, assignedById = null, now = new Date() }, db = prisma) {
const role = await loadRole(roleId, db);
const event = await loadEvent(role.eventId, db);
assertOpen(role, event, now);
if (role.slots.some(s => s.userId === userId)) throw volunteerError(assignedById ? 'This person is already on this role.' : 'You\'re already serving in this role.', 409);
const slot = await db.$transaction(async tx => {
if (!assignedById && await tx.volunteerSlot.count({ where: { roleId: role.id } }) >= role.needed) throw volunteerError('This role is full — thank you for offering!', 409, 'ROLE_FULL');
await assertFree(tx, event, role, userId);
const registrationId = await givePlace(tx, event, userId);
return tx.volunteerSlot.create({ data: { roleId: role.id, userId, assignedById, registrationId } });
});
return { slot, role, event };
}
async function loadSlot(slotId, db = prisma) {
const slot = await db.volunteerSlot.findUnique({ where: { id: String(slotId || '') }, include: { user: { select: USER_SELECT }, role: { include: { session: true } } } });
if (!slot) throw volunteerError('Not found', 404);
return slot;
}
/** Take someone off a role (they withdrew, or a supervisor removed them). Not after check-in. */
async function leave({ slotId, userId = null }, db = prisma) {
const slot = await loadSlot(slotId, db);
if (userId && slot.userId !== userId) throw volunteerError('Not found', 404);
if (slot.checkedInAt) throw volunteerError(`${userId ? 'You\'ve' : `${slot.user.name} has`} already checked in for this shift.`);
const event = await loadEvent(slot.role.eventId, db);
if (userId && shiftOf(slot.role, event).endsAt <= new Date()) throw volunteerError('This shift is already over.');
await db.$transaction(async tx => {
await tx.volunteerSwap.updateMany({ where: { slotId: slot.id, status: 'open' }, data: { status: 'cancelled', resolvedAt: new Date() } });
await releasePlace(tx, slot);
await tx.volunteerSlot.delete({ where: { id: slot.id } });
});
return { slot, event };
}
// ─── Swaps ────────────────────────────────────────────────────────────────────
/** "Can't make it": ask for someone to take over the slot. One open request per slot. */
async function requestSwap({ slotId, userId, note, now = new Date() }, db = prisma) {
const slot = await loadSlot(slotId, db);
if (slot.userId !== userId) throw volunteerError('Not found', 404);
const event = await loadEvent(slot.role.eventId, db);
assertOpen(slot.role, event, now);
if (slot.checkedInAt) throw volunteerError('You\'ve already checked in for this shift.');
const open = await db.volunteerSwap.findFirst({ where: { slotId: slot.id, status: 'open' } });
if (open) return { swap: open, slot, event, created: false };
const swap = await db.volunteerSwap.create({ data: { slotId: slot.id, roleId: slot.roleId, fromUserId: userId, note: cleanText(note, 300) || null } });
return { swap, slot, event, created: true };
}
async function cancelSwap({ swapId, userId }, db = prisma) {
const out = await db.volunteerSwap.updateMany({ where: { id: String(swapId || ''), fromUserId: userId, status: 'open' }, data: { status: 'cancelled', resolvedAt: new Date() } });
if (!out.count) throw volunteerError('Not found', 404);
return { cancelled: true };
}
/**
* Take over a slot someone can't make. Happens at once: the slot moves to the person accepting
* (their reminder and free place are theirs now). Returns { swap, slot, from, to, event }.
*/
async function acceptSwap({ swapId, userId, now = new Date() }, db = prisma) {
const swap = await db.volunteerSwap.findUnique({ where: { id: String(swapId || '') } });
if (!swap || swap.status !== 'open' || !swap.slotId) throw volunteerError('Someone has already taken this place, or it isn\'t needed any more.', 409, 'SWAP_CLOSED');
if (swap.fromUserId === userId) throw volunteerError('This is your own request — cancel it instead.');
const slot = await loadSlot(swap.slotId, db);
const event = await loadEvent(slot.role.eventId, db);
assertOpen(slot.role, event, now);
await db.$transaction(async tx => {
// Claim the request first, so two people accepting at once can't both take it.
const claimed = await tx.volunteerSwap.updateMany({ where: { id: swap.id, status: 'open' }, data: { status: 'accepted', toUserId: userId, resolvedAt: new Date(now) } });
if (!claimed.count) throw volunteerError('Someone has just taken this place.', 409, 'SWAP_CLOSED');
if (await tx.volunteerSlot.count({ where: { roleId: slot.roleId, userId } })) throw volunteerError('You\'re already serving in this role.', 409);
await assertFree(tx, event, slot.role, userId);
await releasePlace(tx, slot);
const registrationId = await givePlace(tx, event, userId);
await tx.volunteerSlot.update({ where: { id: slot.id }, data: { userId, assignedById: null, registrationId, remindedAt: null } });
});
const to = await db.user.findUnique({ where: { id: userId }, select: USER_SELECT });
return { swap, slot, from: slot.user, to, event };
}
/** Open cover requests the person could take (not their own, not a role they're in, not over). */
async function openSwaps({ userId, now = new Date() }, db = prisma) {
const swaps = await db.volunteerSwap.findMany({
where: { status: 'open', fromUserId: { not: userId }, role: { event: { isActive: true, endDate: { gte: now } }, slots: { none: { userId } } } },
include: { role: { include: { session: true, event: { select: EVENT_SELECT } } }, fromUser: { select: { name: true } } },
orderBy: { createdAt: 'asc' },
take: 50,
});
return swaps
.map(w => ({ w, shift: shiftOf(w.role, w.role.event) }))
.filter(({ shift }) => shift.endsAt > new Date(now))
.map(({ w, shift }) => ({
swapId: w.id, note: w.note || '', from: (w.fromUser?.name || '').split(' ')[0] || null,
role: { id: w.role.id, name: w.role.name, sessionLabel: w.role.session ? sessionsUtil.sessionLabel(w.role.session, w.role.event.sessions) : null },
event: { id: w.role.event.id, title: w.role.event.title },
shift: { startsAt: shift.startsAt, endsAt: shift.endsAt, text: shiftText(shift) },
}));
}
// ─── Check-in ─────────────────────────────────────────────────────────────────
/** Put a checked-in volunteer of a kids-room role on duty in that room for the occasion. */
async function startKidsDuty(tx, event, role, userId, now) {
if (!role.kidsRoomId || !event.kidsCheckIn || !event.kidsRoomSetId) return false;
const room = await tx.allocationGroup.findFirst({ where: { id: role.kidsRoomId, setId: event.kidsRoomSetId }, select: { id: true } });
if (!room) return false;
const occasion = kidsOccasion(role, now);
const already = await tx.kidsRoomDuty.findFirst({ where: { userId, occasion, roomId: room.id, endedAt: null } });
if (already) return true;
// One room at a time, as with "I'm on duty".
await tx.kidsRoomDuty.updateMany({ where: { userId, occasion, endedAt: null }, data: { endedAt: new Date(now) } });
await tx.kidsRoomDuty.create({ data: { roomId: room.id, occasion, userId, fromRoster: true, startedAt: new Date(now) } });
return true;
}
async function markCheckedIn(tx, event, slot, { by, method, now }) {
await tx.volunteerSlot.update({ where: { id: slot.id }, data: { checkedInAt: new Date(now), checkedInById: by, checkInMethod: method } });
return startKidsDuty(tx, event, slot.role, slot.userId, now);
}
/**
* A volunteer scanned the event's check-in QR code: check in every slot of theirs whose shift is
* on today. Returns { event, checkedIn: [{ role, kidsRoom }], already }.
*/
async function checkInWithQr({ qr, userId, now = new Date() }, db = prisma) {
const token = String(qr || '').trim().replace(new RegExp(`^${QR_PREFIX}`, 'i'), '');
const found = token ? await db.event.findUnique({ where: { volunteerCheckInToken: token }, select: { id: true } }) : null;
if (!found) throw volunteerError('That isn\'t a volunteer check-in code from this site.', 404, 'BAD_QR');
const event = await loadEvent(found.id, db);
const slots = await db.volunteerSlot.findMany({ where: { userId, role: { eventId: event.id } }, include: { role: { include: { session: true, kidsRoom: { select: { name: true } } } } } });
if (!slots.length) throw volunteerError(`You're not on the volunteer roster for ${event.title}.`, 404, 'NOT_ROSTERED');
const today = slots.filter(s => !s.role.session?.cancelledAt && checkInOpen(shiftOf(s.role, event), now));
if (!today.length) {
const next = slots.map(s => shiftOf(s.role, event)).filter(sh => sh.endsAt > new Date(now)).sort((a, b) => a.startsAt - b.startsAt)[0];
throw volunteerError(next ? `Check-in opens on the day of your shift (${shiftText(next)}).` : 'Your shifts at this event are over.', 400, 'NOT_TODAY');
}
const checkedIn = [];
const already = [];
await db.$transaction(async tx => {
for (const s of today) {
if (s.checkedInAt) { already.push(s.role.name); continue; }
const onDuty = await markCheckedIn(tx, event, s, { by: userId, method: 'qr', now });
checkedIn.push({ role: s.role.name, kidsRoom: onDuty ? s.role.kidsRoom?.name || null : null });
}
});
return { event: { id: event.id, title: event.title }, checkedIn, already };
}
/** Staff tick a volunteer in (or undo it, which also ends their rostered kids-room duty). */
async function checkInManual({ slotId, staffUserId, undo = false, now = new Date() }, db = prisma) {
const slot = await loadSlot(slotId, db);
const event = await loadEvent(slot.role.eventId, db);
if (undo) {
if (!slot.checkedInAt) return { slot, changed: false };
await db.$transaction(async tx => {
await tx.volunteerSlot.update({ where: { id: slot.id }, data: { checkedInAt: null, checkedInById: null, checkInMethod: null } });
if (slot.role.kidsRoomId) await tx.kidsRoomDuty.updateMany({ where: { userId: slot.userId, roomId: slot.role.kidsRoomId, fromRoster: true, endedAt: null }, data: { endedAt: new Date(now) } });
});
return { slot, changed: true };
}
if (slot.checkedInAt) return { slot, changed: false };
if (!checkInOpen(shiftOf(slot.role, event), now) && new Date(now) < shiftOf(slot.role, event).startsAt) {
throw volunteerError(`${slot.user.name} can be checked in on the day of the shift (${shiftText(shiftOf(slot.role, event))}).`);
}
await db.$transaction(tx => markCheckedIn(tx, event, slot, { by: staffUserId, method: 'manual', now }));
return { slot, changed: true };
}
/** For the kids board: who is rostered in each room for an occasion, and whether they've checked in. */
async function rosteredForRooms(event, occasion, db = prisma) {
if (!event.kidsRoomSetId) return {};
const roles = await db.servingRole.findMany({
where: { eventId: event.id, kidsRoom: { setId: event.kidsRoomSetId }, ...(event.scheduleType === 'sessions' ? { sessionId: occasion } : {}) },
include: { session: true, slots: { include: { user: { select: { id: true, name: true } } } } },
});
const out = {};
for (const r of roles) {
// Single-date events: only roles whose shift is on that day.
if (event.scheduleType !== 'sessions') {
const shift = shiftOf(r, event);
if (occasion < sessionsUtil.dayKey(shift.startsAt) || occasion > sessionsUtil.dayKey(shift.endsAt)) continue;
}
for (const s of r.slots) {
(out[r.kidsRoomId] ||= []).push({ userId: s.user.id, name: s.user.name, checkedIn: !!s.checkedInAt });
}
}
return out;
}
// ─── My serving ───────────────────────────────────────────────────────────────
/** The person's upcoming (and the last week's) slots, with open swap requests. */
async function mySlots({ userId, now = new Date() }, db = prisma) {
const since = new Date(new Date(now).getTime() - 7 * 24 * HOUR);
const slots = await db.volunteerSlot.findMany({
where: { userId, role: { event: { endDate: { gte: since } } } },
include: { role: { include: { session: true, kidsRoom: { select: { name: true } }, event: { select: EVENT_SELECT } } }, swaps: { where: { status: 'open' } } },
});
return slots
.map(s => {
const shift = shiftOf(s.role, s.role.event);
return {
slotId: s.id,
role: { id: s.role.id, name: s.role.name, description: s.role.description || '', sessionLabel: s.role.session ? sessionsUtil.sessionLabel(s.role.session, s.role.event.sessions) : null, kidsRoom: s.role.kidsRoom?.name || null },
event: { id: s.role.event.id, title: s.role.event.title, location: s.role.event.location },
shift: { startsAt: shift.startsAt, endsAt: shift.endsAt, text: shiftText(shift), hours: shiftHours(shift) },
checkedInAt: s.checkedInAt,
canCheckIn: !s.checkedInAt && checkInOpen(shift, now),
past: shift.endsAt < new Date(now),
swapId: s.swaps[0]?.id || null,
hasTicket: !!s.registrationId,
};
})
.sort((a, b) => new Date(a.shift.startsAt) - new Date(b.shift.startsAt));
}
/** Upcoming events with serving roles (for "Serve at an event"). */
async function eventsWithRoles({ now = new Date(), where = {} } = {}, db = prisma) {
return db.event.findMany({
where: { AND: [{ isActive: true, endDate: { gte: now }, servingRoles: { some: {} } }, where] },
select: { id: true, title: true, startDate: true, endDate: true, location: true, campusId: true, isHidden: true, _count: { select: { servingRoles: true } } },
orderBy: { startDate: 'asc' },
take: 100,
});
}
// ─── Reports ──────────────────────────────────────────────────────────────────
/**
* Hours served per person over the events matching `eventWhere` (checked-in shifts only), most
* hours first: [{ userId, name, shifts, hours, events }].
*/
async function hoursServed({ eventWhere = {}, from = null, to = null } = {}, db = prisma) {
const slots = await db.volunteerSlot.findMany({
where: { checkedInAt: { not: null, ...(from ? { gte: new Date(from) } : {}), ...(to ? { lte: new Date(to) } : {}) }, role: { event: eventWhere } },
include: { user: { select: { id: true, name: true } }, role: { include: { session: true, event: { select: { id: true, startDate: true, endDate: true, sessions: true } } } } },
});
const byUser = new Map();
for (const s of slots) {
const row = byUser.get(s.userId) || { userId: s.userId, name: s.user.name, shifts: 0, hours: 0, events: new Set() };
row.shifts += 1;
row.hours += shiftHours(shiftOf(s.role, s.role.event));
row.events.add(s.role.event.id);
byUser.set(s.userId, row);
}
return [...byUser.values()].map(r => ({ ...r, events: r.events.size })).sort((a, b) => b.hours - a.hours || a.name.localeCompare(b.name));
}
// ─── Messages ─────────────────────────────────────────────────────────────────
function frontendUrl() {
return String(process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');
}
const servingUrl = () => `${frontendUrl()}/dashboard/user/serving`;
/** Send a text to a volunteer the way they like it (WhatsApp, email, or whichever works). Fire-and-forget. */
function tell(user, { subject, heading, text }) {
if (!user) return Promise.resolve([]);
return require('./kids').messageParent(user, { subject, heading, text }).catch(() => []);
}
/** Email the event's notify recipients (or its creator) about a roster change. */
async function tellOrganisers(eventId, { subject, text }, db = prisma) {
const event = await db.event.findUnique({
where: { id: eventId },
include: { createdBy: { select: { email: true } }, notifyRecipients: { select: { email: true } } },
});
const to = require('./notifications').getEventNotifyEmails(event);
if (!to.length) return;
const { sendMail, buildPrivacyEmail } = require('./email');
await sendMail({ to: to.join(','), subject, ...buildPrivacyEmail({ name: 'team', heading: subject, paragraphs: [text, `Roster: ${frontendUrl()}/dashboard/supervisor/volunteers?event=${eventId}`] }) }).catch(() => {});
}
function placeText(role, event) {
return `${role.name} at ${event.title}${role.session ? ` (${sessionsUtil.sessionLabel(role.session, event.sessions)})` : ''}, ${shiftText(shiftOf(role, event))}`;
}
function signedUpMessages({ user, role, event, by = null }) {
const text = by
? `${by} has put you on the volunteer roster: ${placeText(role, event)}. Thank you for serving! If you can't make it, ask for cover in My account → Serving (${servingUrl()}).`
: `Thank you for volunteering: ${placeText(role, event)}. You'll get a reminder the day before. If you can't make it, ask for cover in My account → Serving (${servingUrl()}).`;
return tell(user, { subject: `Serving: ${role.name} — ${event.title}`, heading: 'You\'re on the roster', text });
}
/** The cover request goes to the event's other volunteers (not the ones already in this role). */
async function sendSwapRequest({ swap, slot, event }, db = prisma) {
const others = await db.volunteerSlot.findMany({
where: { role: { eventId: event.id }, userId: { not: slot.userId }, NOT: { roleId: slot.roleId } },
distinct: ['userId'],
include: { user: { select: USER_SELECT } },
take: 200,
});
const inRole = new Set((await db.volunteerSlot.findMany({ where: { roleId: slot.roleId }, select: { userId: true } })).map(s => s.userId));
const first = (slot.user.name || '').split(' ')[0] || 'A volunteer';
const text = `${first} can't make it and is looking for someone to take over: ${placeText(slot.role, event)}.${swap.note ? ` "${swap.note}"` : ''} If you can, take it over in My account → Serving (${servingUrl()}) — the first to accept gets it.`;
for (const o of others) {
if (inRole.has(o.userId)) continue;
await tell(o.user, { subject: `Cover needed: ${slot.role.name} — ${event.title}`, heading: 'Can you take over?', text });
}
return others.length;
}
async function sendSwapAccepted({ slot, from, to, event }) {
const what = placeText(slot.role, event);
await tell(from, { subject: `${to.name} is taking over — ${event.title}`, heading: 'Your place is covered', text: `${to.name} has taken over ${what}. You're off the roster for it — thank you for finding cover.` });
await tell(to, { subject: `Serving: ${slot.role.name} — ${event.title}`, heading: 'You\'re on the roster', text: `Thank you for taking over from ${from.name}: ${what}. You'll get a reminder the day before.` });
await tellOrganisers(event.id, { subject: `Roster swap: ${slot.role.name} — ${event.title}`, text: `${to.name} has taken over from ${from.name}: ${what}.` });
}
async function sendLeft({ slot, event, byStaff = null }) {
const what = placeText(slot.role, event);
if (byStaff) {
await tell(slot.user, { subject: `Roster change — ${event.title}`, heading: 'Roster change', text: `${byStaff} has taken you off the roster for ${what}. Thank you for being willing to serve.` });
} else {
await tellOrganisers(event.id, { subject: `Volunteer withdrew: ${slot.role.name} — ${event.title}`, text: `${slot.user.name} has withdrawn from ${what}.` });
}
}
async function sendRoleDeleted({ role, event, volunteers }) {
for (const u of volunteers) {
await tell(u, { subject: `Roster change — ${event.title}`, heading: 'Roster change', text: `The ${role.name} role at ${event.title} is no longer needed, so you're off the roster for it. Thank you for being willing to serve.` });
}
}
/** Reminders for shifts starting within the next 24 hours. Returns { sent }. */
async function runReminderJob(now = new Date(), db = prisma) {
const slots = await db.volunteerSlot.findMany({
where: { remindedAt: null, checkedInAt: null, role: { event: { isActive: true, endDate: { gte: now }, startDate: { lte: new Date(new Date(now).getTime() + 31 * 24 * HOUR) } } } },
include: { user: { select: USER_SELECT }, role: { include: { session: true, event: { select: EVENT_SELECT } } } },
take: 2000,
});
let sent = 0;
for (const s of slots) {
if (s.role.session?.cancelledAt) continue;
const shift = shiftOf(s.role, s.role.event);
if (!reminderDue(s, shift, now)) continue;
// Claim it first so a second backend process doesn't send it again.
const claimed = await db.volunteerSlot.updateMany({ where: { id: s.id, remindedAt: null }, data: { remindedAt: new Date(now) } });
if (!claimed.count) continue;
const ev = s.role.event;
const place = ev.location ? ` at ${ev.location}` : '';
await tell(s.user, {
subject: `Reminder: serving ${s.role.name} — ${ev.title}`,
heading: 'See you soon',
text: `A reminder that you're serving: ${placeText(s.role, ev)}${place}. When you arrive, scan the volunteer check-in QR code with your phone. Can't make it? Ask for cover in My account → Serving (${servingUrl()}).`,
});
sent += 1;
}
return { sent };
}
// ─── Privacy ──────────────────────────────────────────────────────────────────
/** For "Download my data". */
async function exportVolunteering(userId, db = prisma) {
const slots = await db.volunteerSlot.findMany({
where: { userId },
include: { role: { include: { session: true, event: { select: { title: true, startDate: true, endDate: true, sessions: true } } } } },
orderBy: { createdAt: 'asc' },
});
return slots.map(s => {
const shift = shiftOf(s.role, s.role.event);
return { event: s.role.event.title, role: s.role.name, from: shift.startsAt, to: shift.endsAt, signedUp: s.createdAt, assigned: !!s.assignedById, checkedIn: s.checkedInAt };
});
}
/**
* For anonymiseUser: shifts still to come are given up (open places, free tickets released);
* past ones stay for the hours-served totals, under the anonymised account. Swap notes go.
*/
async function forgetVolunteer(tx, userId, now = new Date()) {
const slots = await tx.volunteerSlot.findMany({ where: { userId, checkedInAt: null }, include: { role: { include: { session: true, event: { select: { startDate: true, endDate: true, sessions: true } } } } } });
let removed = 0;
for (const s of slots) {
if (shiftOf(s.role, s.role.event).endsAt <= new Date(now)) continue;
await tx.volunteerSwap.updateMany({ where: { slotId: s.id, status: 'open' }, data: { status: 'cancelled', resolvedAt: new Date(now) } });
await releasePlace(tx, s);
await tx.volunteerSlot.delete({ where: { id: s.id } });
removed += 1;
}
await tx.volunteerSwap.updateMany({ where: { OR: [{ fromUserId: userId }, { toUserId: userId }], note: { not: null } }, data: { note: null } });
return removed;
}
module.exports = {
QR_PREFIX, MAX_NEEDED, volunteerError,
shiftOf, overlaps, shiftHours, fillOf, checkInOpen, reminderDue, kidsOccasion, reservedOptionIds, publicOptions, shiftText,
loadEvent, roleView, roster, createRole, updateRole, deleteRole, getSettings, saveSettings, checkInQr,
givePlace, releasePlace, signUp, leave, requestSwap, cancelSwap, acceptSwap, openSwaps,
checkInWithQr, checkInManual, rosteredForRooms, mySlots, eventsWithRoles, hoursServed,
signedUpMessages, sendSwapRequest, sendSwapAccepted, sendLeft, sendRoleDeleted, runReminderJob,
exportVolunteering, forgetVolunteer,
};
@@ -0,0 +1,92 @@
const v = require('../src/utils/volunteers');
const { isBlocked } = require('../src/hub/readOnly');
const event = {
id: 'e1', startDate: new Date('2026-11-08T06:00:00Z'), endDate: new Date('2026-11-08T10:00:00Z'),
sessions: [{ id: 's1', startsAt: new Date('2026-11-15T16:30:00Z'), endsAt: new Date('2026-11-15T18:30:00Z') }],
};
describe('shifts', () => {
test("a role's shift: its own times, else its session's, else the event's", () => {
expect(v.shiftOf({}, event)).toEqual({ startsAt: event.startDate, endsAt: event.endDate });
expect(v.shiftOf({ sessionId: 's1' }, event)).toEqual({ startsAt: event.sessions[0].startsAt, endsAt: event.sessions[0].endsAt });
const own = { startsAt: '2026-11-08T05:30:00Z', endsAt: '2026-11-08T07:00:00Z' };
expect(v.shiftOf(own, event)).toEqual({ startsAt: new Date(own.startsAt), endsAt: new Date(own.endsAt) });
});
test('overlapping shifts; touching ends are fine', () => {
const a = { startsAt: '2026-11-08T06:00:00Z', endsAt: '2026-11-08T08:00:00Z' };
expect(v.overlaps(a, { startsAt: '2026-11-08T07:00:00Z', endsAt: '2026-11-08T09:00:00Z' })).toBe(true);
expect(v.overlaps(a, { startsAt: '2026-11-08T08:00:00Z', endsAt: '2026-11-08T09:00:00Z' })).toBe(false);
expect(v.overlaps(a, { startsAt: '2026-11-08T05:00:00Z', endsAt: '2026-11-08T06:00:00Z' })).toBe(false);
});
test('hours to the nearest quarter hour', () => {
expect(v.shiftHours({ startsAt: '2026-11-08T06:00:00Z', endsAt: '2026-11-08T08:30:00Z' })).toBe(2.5);
expect(v.shiftHours({ startsAt: '2026-11-08T06:00:00Z', endsAt: '2026-11-08T06:50:00Z' })).toBe(0.75);
expect(v.shiftHours({ startsAt: '2026-11-08T06:00:00Z', endsAt: '2026-11-08T06:00:00Z' })).toBe(0);
});
test('fill', () => {
expect(v.fillOf(4, 3)).toEqual({ needed: 4, filled: 3, open: 1, full: false });
expect(v.fillOf(2, 3)).toEqual({ needed: 2, filled: 3, open: 0, full: true });
});
});
describe('check-in window', () => {
const shift = { startsAt: new Date('2026-11-08T06:00:00Z'), endsAt: new Date('2026-11-08T08:00:00Z') };
test('open on the day of the shift until it ends', () => {
expect(v.checkInOpen(shift, new Date('2026-11-08T04:00:00Z'))).toBe(true); // early, same day (SAST)
expect(v.checkInOpen(shift, new Date('2026-11-08T07:59:00Z'))).toBe(true);
});
test('closed the day before and after the shift ends', () => {
expect(v.checkInOpen(shift, new Date('2026-11-07T12:00:00Z'))).toBe(false);
expect(v.checkInOpen(shift, new Date('2026-11-08T08:01:00Z'))).toBe(false);
});
});
describe('reminders', () => {
const shift = { startsAt: new Date('2026-11-08T06:00:00Z'), endsAt: new Date('2026-11-08T08:00:00Z') };
const signedUp = new Date('2026-11-01T10:00:00Z');
test('due within 24 hours of the start, once', () => {
expect(v.reminderDue({ remindedAt: null, createdAt: signedUp }, shift, new Date('2026-11-07T07:00:00Z'))).toBe(true);
expect(v.reminderDue({ remindedAt: new Date(), createdAt: signedUp }, shift, new Date('2026-11-07T07:00:00Z'))).toBe(false);
});
test('not too early, not after the start', () => {
expect(v.reminderDue({ remindedAt: null, createdAt: signedUp }, shift, new Date('2026-11-07T05:00:00Z'))).toBe(false);
expect(v.reminderDue({ remindedAt: null, createdAt: signedUp }, shift, new Date('2026-11-08T06:00:00Z'))).toBe(false);
});
test('not for someone who signed up minutes ago', () => {
const now = new Date('2026-11-07T20:00:00Z');
expect(v.reminderDue({ remindedAt: null, createdAt: new Date(now.getTime() - 10 * 60 * 1000) }, shift, now)).toBe(false);
});
});
describe('kids rooms', () => {
test('a session role counts for its session; otherwise for the day', () => {
expect(v.kidsOccasion({ sessionId: 's1' })).toBe('s1');
expect(v.kidsOccasion({ sessionId: null }, new Date('2026-11-08T06:00:00Z'))).toBe('2026-11-08');
});
});
describe('reserved tickets', () => {
test('the kids and volunteer tickets never show publicly', () => {
const ev = { kidsOptionId: 'k', volunteerOptionId: 'vol', eventOptions: [{ id: 'adult' }, { id: 'k' }, { id: 'vol' }] };
expect(v.reservedOptionIds(ev)).toEqual(['k', 'vol']);
expect(v.publicOptions(ev).map(o => o.id)).toEqual(['adult']);
expect(v.publicOptions({ eventOptions: [{ id: 'a' }] }).map(o => o.id)).toEqual(['a']);
});
});
describe('read-only licence', () => {
test.each([
['POST', '/api/volunteers/roles/r1/sign-up'],
['POST', '/api/volunteers/manage/events/e1/roles'],
['POST', '/api/volunteers/manage/roles/r1/assign'],
])('%s %s is blocked', (m, p) => expect(isBlocked(m, p)).toBe(true));
test.each([
['POST', '/api/volunteers/check-in'],
['POST', '/api/volunteers/swaps/w1/accept'],
['DELETE', '/api/volunteers/slots/s1'],
])('%s %s keeps working', (m, p) => expect(isBlocked(m, p)).toBe(false));
});