diff --git a/apps/events/backend/prisma/migrations/20261028120000_volunteer_rosters/migration.sql b/apps/events/backend/prisma/migrations/20261028120000_volunteer_rosters/migration.sql new file mode 100644 index 0000000..5f96584 --- /dev/null +++ b/apps/events/backend/prisma/migrations/20261028120000_volunteer_rosters/migration.sql @@ -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; + diff --git a/apps/events/backend/prisma/schema.prisma b/apps/events/backend/prisma/schema.prisma index d3eb927..884d9cd 100644 --- a/apps/events/backend/prisma/schema.prisma +++ b/apps/events/backend/prisma/schema.prisma @@ -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]) +} diff --git a/apps/events/backend/src/controllers/eventController.js b/apps/events/backend/src/controllers/eventController.js index b17ad09..b126b8c 100644 --- a/apps/events/backend/src/controllers/eventController.js +++ b/apps/events/backend/src/controllers/eventController.js @@ -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'); diff --git a/apps/events/backend/src/controllers/registrationController.js b/apps/events/backend/src/controllers/registrationController.js index 48cb959..ff625b4 100644 --- a/apps/events/backend/src/controllers/registrationController.js +++ b/apps/events/backend/src/controllers/registrationController.js @@ -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). diff --git a/apps/events/backend/src/controllers/volunteerController.js b/apps/events/backend/src/controllers/volunteerController.js new file mode 100644 index 0000000..ce2c6f2 --- /dev/null +++ b/apps/events/backend/src/controllers/volunteerController.js @@ -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, +}; diff --git a/apps/events/backend/src/hub/readOnly.js b/apps/events/backend/src/hub/readOnly.js index c2e4cf6..5244497 100644 --- a/apps/events/backend/src/hub/readOnly.js +++ b/apps/events/backend/src/hub/readOnly.js @@ -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) { diff --git a/apps/events/backend/src/index.js b/apps/events/backend/src/index.js index 4d2d648..c5e759c 100644 --- a/apps/events/backend/src/index.js +++ b/apps/events/backend/src/index.js @@ -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:[] }}]}, diff --git a/apps/events/backend/src/jobs/index.js b/apps/events/backend/src/jobs/index.js index e37f800..d16d5d5 100644 --- a/apps/events/backend/src/jobs/index.js +++ b/apps/events/backend/src/jobs/index.js @@ -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 () => { diff --git a/apps/events/backend/src/routes/volunteerRoutes.js b/apps/events/backend/src/routes/volunteerRoutes.js new file mode 100644 index 0000000..fc66a09 --- /dev/null +++ b/apps/events/backend/src/routes/volunteerRoutes.js @@ -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; diff --git a/apps/events/backend/src/utils/accessLog.js b/apps/events/backend/src/utils/accessLog.js index 255f61a..c0dbad1 100644 --- a/apps/events/backend/src/utils/accessLog.js +++ b/apps/events/backend/src/utils/accessLog.js @@ -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', }; /** diff --git a/apps/events/backend/src/utils/campusScope.js b/apps/events/backend/src/utils/campusScope.js index 17b9b1b..69babeb 100644 --- a/apps/events/backend/src/utils/campusScope.js +++ b/apps/events/backend/src/utils/campusScope.js @@ -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. */ diff --git a/apps/events/backend/src/utils/kids.js b/apps/events/backend/src/utils/kids.js index 5932ad4..32110c1 100644 --- a/apps/events/backend/src/utils/kids.js +++ b/apps/events/backend/src/utils/kids.js @@ -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, }; diff --git a/apps/events/backend/src/utils/notifications.js b/apps/events/backend/src/utils/notifications.js index a7d79d1..fba6d68 100644 --- a/apps/events/backend/src/utils/notifications.js +++ b/apps/events/backend/src/utils/notifications.js @@ -1513,6 +1513,7 @@ async function sendAttendeeFormLinkMessage(attendee) { } module.exports = { + getEventNotifyEmails, buildEventNotifyRecipientList, sendAttendeeFormLinkMessage, sendRegistrationEmails, diff --git a/apps/events/backend/src/utils/privacy.js b/apps/events/backend/src/utils/privacy.js index cb9a610..f4f478f 100644 --- a/apps/events/backend/src/utils/privacy.js +++ b/apps/events/backend/src/utils/privacy.js @@ -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) { diff --git a/apps/events/backend/src/utils/volunteers.js b/apps/events/backend/src/utils/volunteers.js new file mode 100644 index 0000000..cbef913 --- /dev/null +++ b/apps/events/backend/src/utils/volunteers.js @@ -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, +}; diff --git a/apps/events/backend/tests/volunteers.test.js b/apps/events/backend/tests/volunteers.test.js new file mode 100644 index 0000000..eabcbb1 --- /dev/null +++ b/apps/events/backend/tests/volunteers.test.js @@ -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)); +});