The rest of event set-up on API v2 (1.51.8)

- v2: event in full, calendar file, alias, ticket options and variants, attachments
  (multipart), sections, planned costs, image uploads.
- src/services/eventDetails.ts and src/services/setup.ts; v1 uses them.
- v2 routes can send files (fileResponse) and take uploads (documented as multipart).
- Frontend: fetchEvent() everywhere, lib/eventSetup.ts for set-up calls.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ls1vMdg2GYqbnKZmPaX1ot

.gitea/workflows/ci.yml

@@ -1,129 +0,0 @@
-# Checks every push and pull request: backend tests, frontend lint/typecheck/build, and
-# the Playwright end-to-end tests. Pushing a version tag (v1.2.3) also deploys, once the
-# DEPLOY_* secrets are set (Repository → Settings → Actions → Secrets).
-#
-# Needs a Gitea Actions runner with the "ubuntu-latest" label (Docker), e.g. act_runner:
-# https://docs.gitea.com/usage/actions/act-runner
-name: CI
-
-on:
-  push:
-    branches: ["**"]
-    tags: ["v*"]
-  pull_request:
-
-env:
-  NODE_VERSION: "20"
-  # Throwaway values for the test database and tokens — never production secrets.
-  JWT_SECRET: ci-only-jwt-secret-not-for-production
-  DATABASE_URL: postgresql://postgres:postgres@postgres:5432/events_ci
-  E2E_DATABASE_URL: postgresql://postgres:postgres@postgres:5432/events_ci_e2e
-
-jobs:
-  backend:
-    name: Backend tests
-    runs-on: ubuntu-latest
-    services:
-      postgres:
-        image: postgres:16
-        env:
-          POSTGRES_PASSWORD: postgres
-          POSTGRES_DB: events_ci
-        options: >-
-          --health-cmd "pg_isready -U postgres" --health-interval 5s --health-timeout 5s --health-retries 10
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: npm
-          cache-dependency-path: backend/package-lock.json
-      - run: npm ci
-        working-directory: backend
-      - name: Migrations apply cleanly
-        run: npx prisma migrate deploy
-        working-directory: backend
-      - run: npm test
-        working-directory: backend
-
-  frontend:
-    name: Frontend lint, typecheck, build
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: npm
-          cache-dependency-path: frontend/package-lock.json
-      - run: npm ci
-        working-directory: frontend
-      - run: npx eslint src
-        working-directory: frontend
-      - run: npx tsc --noEmit -p .
-        working-directory: frontend
-      - run: npm run build
-        working-directory: frontend
-        env:
-          NEXT_PUBLIC_API_URL: http://localhost:5000
-          NEXT_TELEMETRY_DISABLED: "1"
-
-  e2e:
-    name: End-to-end tests
-    runs-on: ubuntu-latest
-    needs: [backend, frontend]
-    services:
-      postgres:
-        image: postgres:16
-        env:
-          POSTGRES_PASSWORD: postgres
-          POSTGRES_DB: events_ci
-        options: >-
-          --health-cmd "pg_isready -U postgres" --health-interval 5s --health-timeout 5s --health-retries 10
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-      - run: npm ci
-      - run: npm ci
-        working-directory: backend
-      - run: npm ci
-        working-directory: frontend
-      - run: npx playwright install --with-deps chromium
-      - run: npx playwright test
-        env:
-          CI: "true"
-      - name: Keep the report when tests fail
-        if: failure()
-        uses: actions/upload-artifact@v3
-        with:
-          name: playwright-report
-          path: |
-            e2e/report
-            e2e/test-results
-          retention-days: 7
-
-  deploy:
-    name: Deploy tagged release
-    runs-on: ubuntu-latest
-    needs: [backend, frontend, e2e]
-    if: startsWith(github.ref, 'refs/tags/v')
-    steps:
-      - name: Deploy over SSH (skipped until DEPLOY_HOST is set)
-        env:
-          DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
-          DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
-          DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
-          DEPLOY_PATH: ${{ secrets.DEPLOY_PATH }}
-          TAG: ${{ github.ref_name }}
-        run: |
-          if [ -z "$DEPLOY_HOST" ]; then
-            echo "DEPLOY_HOST isn't set — skipping the deploy."
-            exit 0
-          fi
-          mkdir -p ~/.ssh
-          echo "$DEPLOY_SSH_KEY" > ~/.ssh/deploy_key
-          chmod 600 ~/.ssh/deploy_key
-          ssh -i ~/.ssh/deploy_key -o StrictHostKeyChecking=accept-new "$DEPLOY_USER@$DEPLOY_HOST" \
-            "cd '${DEPLOY_PATH:-~/hope-events}' && bash scripts/deploy.sh '$TAG'"

CHANGELOG.md

@@ -7,6 +7,606 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.51.8] - 2026-10-29
+
+### Added
+
+- **API v2 — the rest of setting events up:** `GET /events/{id}/full` (the event in full — what's
+  left per ticket, variant and session, form, attachments, bundles, next in series; staff also see
+  inactive events, creator and email recipients), `GET /events/{id}/calendar.ics`,
+  `GET /events/by-alias/{alias}`; ticket options (`POST /events/{id}/ticket-options`,
+  `PATCH`/`DELETE /ticket-options/{id}`) and variants (`POST /ticket-options/{id}/variants`,
+  `PATCH`/`DELETE /variants/{id}`); attachments (`GET`/`POST /events/{id}/attachments` — multipart —
+  and `DELETE …/{attachmentId}`, admin `/attachments/status` and `/attachments/sync`); scanning
+  sections (`/sections`); planned costs (`/events/{id}/costs`, `/costs/{id}`); image uploads
+  (`/uploads/event-image`, `/uploads/logo`, `/uploads/favicon` — returning `path` and `url`).
+- **Services:** `src/services/eventDetails.ts` (from eventController.js, now 1,080 lines, from 2,217
+  at the start of 1.51.7) and `src/services/setup.ts` (sections and costs). v1 uses them too.
+- **v2 route features:** `file` routes answer with a download (`fileResponse`), and `upload` routes
+  are described as multipart in the OpenAPI document.
+- Frontend: `fetchEvent()` for every event page (the public event and registration pages too),
+  and `lib/eventSetup.ts` for ticket options, sections, attachments, costs and image uploads.
+
+### Changed
+
+- The pre-migration fallbacks for attachments (JSON manifests on disk) are gone from the normal
+  path; old manifests can still be imported with `/attachments/sync`.
+- v1's `GET /api/events/:id` now points at `/api/v2/events/{id}/full` as its successor.
+- Roadmap: series, season passes, bundles, coupons and campuses are 1.51.9; later areas move up one
+  (to 1.51.15).
+
+## [1.51.7] - 2026-10-29
+
+### Added
+
+- **API v2 — setting events up:** `GET /events/manage` (every event staff may see, hidden ones too;
+  `past`, `inactive`, `closed`; campus-scoped), `POST /events`, `PATCH /events/{id}` (only what's sent
+  changes; `sessionChanges` when sessions were sent), `DELETE /events/{id}` (admins; deactivates),
+  `POST /events/{id}/copy-from`, and `GET`/`PUT /events/{id}/notify-recipients`. Event records are
+  typed for their core fields and pass the rest through as stored (`z.looseObject`).
+- **`src/services/events.ts`:** create, update, deactivate, the staff list, notify recipients and
+  copy-from moved out of `eventController.js` (2,217 → 1,717 lines), with the schedule helpers
+  (`withSchedule`, `scheduleData`, `saveSchedule`). v1 uses it too. The pre-migration fallbacks
+  (retrying without `registrationDeadline`, `goLiveAt`…) are gone — every install has those columns.
+  Creating an event now also returns its ticket options.
+- Frontend: `fetchManagedEvents()` (`lib/api.ts`) — every event picker, the kiosk, reports and the
+  set-up screens load events through v2; the event wizard creates, saves, copies and sets
+  notification recipients through v2. v1 deprecation links for these endpoints.
+
+### Changed
+
+- **pg-boss 11** (servers are on Node 24). It can't upgrade pg-boss 10's tables, so the job queue
+  uses a new schema, `pgboss_v11`; schedules are recreated at start, and the admin page's
+  "recent runs" start again from this release. The old `pgboss` schema is left as it was (it can
+  be dropped: `DROP SCHEMA pgboss CASCADE;`). pg-boss 11 brings cron-parser 5, so the last
+  cron-parser 4 deprecation is gone.
+- Roadmap: the rest of the events area (event details for staff, ticket options and variants,
+  attachments, sections, costs, series, season passes, bundles, coupons, campuses, calendar file,
+  alias) is 1.51.8; the later areas move up one (to 1.51.14).
+
+## [1.51.6] - 2026-10-29
+
+### Fixed
+
+- **Command palette (Ctrl+K) was missing things.** It listed 9 of the 19 reports — now every
+  report (built from the report catalogue, so new ones appear by themselves), plus Dashboard,
+  Reports, Ticket options and My groups, and your own pages (My events & tickets, My payments,
+  My privacy, My kids, My serving, My attendee forms, Make a donation). Attendee forms now opens
+  for staff and supervisors too (the page allows them; the palette had it as admin-only). An e2e
+  test fails when a dashboard page is neither in the palette nor deliberately left out.
+
+### Changed
+
+- **Excel exports use ExcelTS** (`@cj-tech-master/excelts` 10) instead of exceljs, which is
+  unmaintained: same API, no dependencies — the backend has 87 fewer packages and none of
+  exceljs's deprecated ones (fstream, glob 7, inflight, lodash.isequal, rimraf 2). New
+  `e2e/excel.spec.ts` opens a real report and attendance export. ExcelTS itself now says it's no
+  longer developed (its successor, documonster, is pre-1.0); existing versions keep working.
+- The backend needs **Node 22 or newer** (`engines`); the servers run Node 24 LTS.
+- Roadmap: incoming webhooks and links in sent messages get v2 URLs too (1.51.13), with the v1 paths
+  still answering; the area releases are now 1.51.7 – 1.51.13.
+
+## [1.51.5] - 2026-10-29
+
+### Changed
+
+- **Next.js 16** (from 15.5) and **React 19.3**. Builds and dev use Turbopack (Next 16's default);
+  `tsconfig.json` `jsx` is `react-jsx` (required by Next 16); `images.domains` → `remotePatterns`.
+- **ESLint 10** (ESLint 9 is out of support) with Next 16's own flat configs
+  (`eslint-config-next/core-web-vitals` and `/typescript`, no more FlatCompat). `npm run lint` is
+  `eslint src` (`next lint` was removed). Next 16's React Compiler-era rules
+  (`react-hooks/set-state-in-effect`, `purity`, `immutability`, `static-components`, `refs`) are
+  warnings for now — 181 places, mostly loading data in `useEffect`.
+- Removed the empty `middleware.ts` (a pass-through that did nothing; Next 16 renames middleware to
+  "proxy"), which also drops its 117 kB bundle.
+
+## [1.51.4] - 2026-10-29
+
+### Security
+
+- **Next.js 15.5.28** (critical: remote code execution through the image optimiser with SVGs, and a
+  Server Actions denial of service), **@sentry/nextjs 10.78** (critical: middleware bypass),
+  **zod 4.6.7** (high: memory exhaustion on oversized collections; backend and frontend),
+  **multer 2.5.0** (high: denial of service from a pending file filter), **nodemailer 10.3.0**
+  (moderate: three address-parsing flaws that could add recipients), fast-uri 3.1.9 and
+  ip-address 10.7.5 (moderate). Minimum versions raised in package.json so a fresh install can't
+  resolve an older one. `npm audit`: frontend and root clean; the backend's 6 remaining reports are
+  low and dev-only (jest → deepmerge), with no real fix (npm suggests downgrading Jest to 25).
+
+### Changed
+
+- **cron-parser 5** (v4 is unmaintained): `CronExpressionParser.parse` in `src/jobs/index.js`.
+- **Node 24 LTS** for new installs (`scripts/install.sh`); Node 20 reached end of life in April 2026.
+  `deploy.sh` warns on servers older than Node 22; DEPLOYMENT.md has "Upgrading Node".
+- Roadmap: every endpoint moves to v2 before 2.0 (1.51.5 – 1.51.11).
+
+### Known
+
+- Still deprecated, with reasons: exceljs (unmaintained; brings fstream, glob 7, inflight,
+  lodash.isequal, rimraf 2) — replacing it with ExcelTS waits for approval; ESLint 9 (out of
+  support) — ESLint 10 needs Next.js 16 (1.51.5); @opentelemetry/sdk-trace-base — pulled in by the
+  latest @sentry/nextjs, for Sentry to update; glob 10 — inside Jest (dev only).
+
+## [1.51.3] - 2026-10-29
+
+### Changed
+
+- **Express 5** (from 4). Kept Express 4 behaviour where it changed: the `qs` ("extended") query
+  parser, and `req.body` as `{}` when a request has no JSON body. `@types/express` 5.
+- **The ticket scanner and at-the-door check-in use API v2** (`/api/v2/checkin/{qrCode}`). The v2
+  look-up now gives `attendee`, `bookedBy` and `ticketOptionId` (for section checks).
+- **Shared middleware answers in the v2 shape on /api/v2:** rate limits, the impersonation and
+  licence read-only guards, the auth checks and campus refusals write v1's `{ message, code }`;
+  on v2 that becomes `{ error: { code, message, reason } }` (`reason` = the specific old code, e.g.
+  `TWO_FACTOR_REQUIRED`, `LICENCE_READ_ONLY`). Read-only answers have the v2 code `READ_ONLY` (403).
+  The frontend's `apiFetch` treats `reason` like v1's `code`, so the 2FA and impersonation
+  handling works on v2 calls too.
+
+### Added
+
+- **v1 deprecation headers:** v1 endpoints that have a v2 replacement answer with
+  `Deprecation: @<date>` (RFC 9745) and `Link: <…>; rel="successor-version"` (`src/v2/deprecation.ts`).
+  The rest of v1 has no replacement yet, so no header.
+
+## [1.51.2] - 2026-10-29
+
+### Added
+
+- **API v2 accounts:** `POST /auth/signup` (needs `acceptTerms`), `POST /auth/login` (answers
+  `signed_in` with a token, or `code_required` for two-factor) and `POST /auth/login/code`, both
+  behind the login rate limit; `PATCH /me` (only what is sent changes; a new password needs the
+  current one) and `GET /me` now with `notificationPreference` and `homeCampusId`.
+- **API v2 check-in:** `GET /checkin/{qrCode}` (look up: holder, what's left, session, consent)
+  and `POST /checkin/{qrCode}` (check in everyone left or `people`). Every normal result is a 200
+  with an `outcome` — `checked_in`, `already_used`, `consent_required`, `wrong_event`,
+  `wrong_section`, `section_not_found`, `no_session`, `locked`, `transferred`. Staff only, with the
+  same campus rule as v1.
+- **Services:** sign up, log in, the 2FA step and profile changes moved from `userController.js`
+  (~430 lines shorter) to `src/services/auth.ts`; scan preview and scanning from
+  `ticketController.js` to `src/services/checkin.ts`. v1 answers exactly as before (`ServiceError`
+  can carry the old `v1Status`, e.g. 400 for a wrong password, which is 401 in v2).
+- v2 routes can take extra middleware (`middleware: [loginLimiter]`).
+
+### Changed
+
+- Logging in (and the 2FA code step), signing up, and changing your details or password use API v2.
+  The scanner stays on v1 until 1.51.3.
+
+## [1.51.1] - 2026-10-29
+
+### Added
+
+- **API v2 registrations and payments:** `POST /registrations` (signed in, guest for free
+  events, or a waitlist link), `GET /registrations/{id}`, `POST /registrations/{id}/cancel` and
+  `POST /registrations/{id}/checkout` (online payment, with an optional donation; answers
+  `priceUpdated` with the new balance when an early-bird price ran out). Owners only (admins too);
+  someone else's registration is `NOT_FOUND`.
+- **Services in TypeScript:** making and cancelling registrations moved from
+  `registrationController.js` to `src/services/registrations.ts`, and paying a registration
+  online from `paymentController.js` to `src/services/payments.ts`. v1 and v2 run the same code;
+  `ServiceError` carries the HTTP status. `registrationController.js` is ~560 lines shorter.
+- **Typed frontend calls:** `npm run api:types` (repo root) writes the OpenAPI document to
+  `frontend/src/lib/api-v2/openapi.json` and generates `schema.d.ts` from it (openapi-typescript);
+  `apiV2(method, path, { params, query, body, authToken })` in `frontend/src/lib/apiV2.ts` checks
+  the path, parameters, body and answer. A backend test fails while the saved document is stale.
+
+### Changed
+
+- The register page, "Pay now" (registration success page and My Events) and cancelling on My
+  Events use API v2. `apiFetch` reads v2 errors (`error.message`, with `code`/`fields` in `data`).
+
+## [1.51.0] - 2026-10-29
+
+### Added
+
+- **API v2** (`/api/v2`), the groundwork for 2.0: every endpoint is declared once with zod
+  schemas (`src/v2/route.ts`). The declaration validates the request, strips the response to what
+  the schema lists, and generates the **OpenAPI 3.1** document (`GET /api/v2/openapi.json`, admin)
+  shown at **`/docs/v2`** (Swagger UI, served locally). One error shape
+  `{ error: { code, message, fields? } }` with stable codes, and one list shape
+  `{ data, meta: { page, limit, total, pages } }`. First endpoints (read-only): `GET /events`,
+  `GET /events/:id`, `GET /me`, `GET /me/registrations`. v1 (`/api/…`) is unchanged.
+- **TypeScript in the backend:** `tsconfig.json` (`allowJs`; `.ts` strict), `npm run build` →
+  `dist/`, `npm run typecheck`, `npm run dev` through tsx, Jest runs `.ts` via ts-jest. Typed
+  doors into JS modules in `src/v2/legacy.ts`.
+- Tests: `tests/v2.test.ts`, e2e `e2e/api-v2.spec.ts`.
+
+### Changed
+
+- The server moved from `backend/src/index.js` to `backend/src/app.js`. `src/index.js` is now a
+  launcher that runs the matching build in `dist/` (or compiles on the fly with tsx when there is
+  none), so existing PM2 configs keep working unchanged.
+- `scripts/deploy.sh` and `scripts/install.sh` build the backend (`npm ci --include=dev`, then
+  `npm run build`); a rollback to a release before 1.51.0 skips the build. The first update to
+  1.51.0 by an older deploy script still starts (it compiles at start-up); the next update builds.
+- e2e starts the backend with tsx.
+
+## [1.50.2] - 2026-10-29
+
+### Added
+
+- **Searchable event picker** (`components/shared/EventPicker.tsx`) instead of the plain event
+  dropdowns on staff and supervisor pages (scanner, event tickets, at the door, payments, manual,
+  email and WhatsApp attendees, forms, attendance, consent, waitlist, allocations, bundles, offline
+  scans, kids and volunteer set-up, manage registrations, the kiosk). It opens on upcoming events
+  (soonest first); past ones are behind **Show past events** (latest first), and typing searches
+  every event by name, campus or date. Keyboard: arrows, Page Up/Down, Enter, Escape.
+- **Reports:** the events list can be searched; "Select these N" / "Clear these" act on the matches.
+- **Site settings → Webhooks → How webhooks work:** what is sent and when, the envelope and
+  headers, retries and duplicates, checking the signature (Node.js and PHP), Zapier/Make set-up,
+  and a copyable example of every event type. `GET /api/outbound-webhooks` event types now carry
+  an `example`; `tests/webhooks.test.js` checks each one has the same shape as the real payload.
+
+### Changed
+
+- Pages that listed every event ever made in their dropdown (email and WhatsApp attendees, forms,
+  bundles, scanner, payments) now open on upcoming ones; their separate "Include past events"
+  checkboxes are gone (the picker has its own). Event tickets and Payments can now reach past
+  events too.
+- e2e: `pickEvent()` in `e2e/fixtures.ts`; `e2e/event-picker.spec.ts`.
+
+## [1.50.1] - 2026-10-29
+
+### Added
+
+- **Audit log:** search by person (name or email), target (type or `#id`) or IP, a Role filter,
+  **Clear filters**, and "21–40 of 312" under the list. The Action filter now lists every action
+  that can be logged (it was missing 35 — campuses, kids check-in, volunteers, series, season
+  passes, webhooks, bulk actions, Hub updates, certificates and more), sorted by name.
+- **Data requests:** search by name or email, and closed requests a page (50) at a time — the list
+  used to stop silently at 200.
+- **Webhook delivery log:** filter by status (failed, retrying, succeeded) and **Load older** —
+  it used to show only the latest 50.
+- API filters: `/api/registrations?unpaid=1&userId=`, `/api/payments?userId=&from=&donations=1`,
+  `/api/privacy/requests?search=&page=&limit=`, `/api/outbound-webhooks/:id/deliveries?before=`,
+  `/api/admin/audit-log?search=&role=`. Shared `components/shared/Pager.tsx`.
+
+### Fixed
+
+- Audit log: the **To** date left out that day's entries (it meant midnight at the start of the
+  day). Both dates are now whole days in the site's time zone.
+
+### Changed
+
+- **Payments** (supervisor) no longer downloads every payment and registration ever made when it
+  opens: it loads the latest payments, today's (for the totals), donations with what they were
+  applied to, and only registrations still owing. Refunds load the chosen person's own payments and
+  registrations when they're picked. Faster as the years add up; the page works the same.
+
+## [1.50.0] - 2026-10-28
+
+### Added
+
+- **Accessibility pass (WCAG 2.2 AA)** on the public pages, sign-in/sign-up, registration,
+  payment, My Events and the self-service kiosk:
+  - **Keyboard:** a "Skip to main content" link as the first Tab stop on every page; a clear focus
+    ring (in the brand colour) on everything you can tab to; popups (Contact us, Join the waitlist,
+    Sponsor a spot, Transfer ticket, the registration popup and send dialogs on My Events, the kiosk's
+    Change Event and Confirm account changes) are announced as dialogs, take focus when they open,
+    keep Tab inside, close with Escape and hand focus back. The kiosk's "Create an account" switch
+    and its password eye can now be used with the keyboard.
+  - **Screen readers:** every form field on those pages has a label tied to it (sign-in, sign-up,
+    forgot/reset password, activation, profile, privacy centre, payments filters, donate, forms,
+    feedback, consent, waitlist, sponsorship, transfer, kiosk and its custom questions); ticket
+    quantity buttons say what they do ("Add one Adult", "Remove one Adult") and the number is
+    announced; option buttons say which one is chosen; error messages are announced when they
+    appear.
+  - **Colour:** light grey text darkened to meet 4.5:1, and links inside sentences are underlined
+    so they don't rely on colour alone. The page honours "reduce motion" on the device.
+  - **Branding:** Site settings → Branding (and the setup wizard) warn when the primary colour is
+    too light for white text and links (under 4.5:1) and offer a darker shade of it in one click.
+- Automated accessibility checks: `e2e/accessibility.spec.ts` runs axe-core (WCAG 2.0–2.2 A/AA
+  rules) on those pages, plus keyboard tests (skip link, popup focus and Escape, ticket quantities,
+  the kiosk switch). New dev dependency `@axe-core/playwright`.
+- `components/shared/ModalOverlay.tsx` for the app's own popups, and `components/layout/SkipLink.tsx`.
+
+### Changed
+
+- e2e tests click ticket quantities by name (`/^Add one /`) instead of "+".
+
+## [1.49.2] - 2026-10-28
+
+### Added
+
+- **Saved filters** on Manage registrations, Users, Events and Reports: set the filters, then
+  **Saved filters → Save** under a name; click one to apply it; **★** makes it the default, applied
+  when the page opens (but not over a link that already says what to show, such as the
+  dashboard's "Waiting for you"). Reports remember the report, events, dates, campus and the
+  past/inactive/closed options. Per person, stored on the server (up to 30 per page), removed when
+  an account is anonymised.
+- `/api/saved-filters` (list, save, rename/default, delete — your own only). Migration
+  `20261028180000_saved_filters`.
+
+## [1.49.1] - 2026-10-28
+
+### Added
+
+- **Bulk actions on registrations** (Admin → Manage registrations): tick registrations, or "Select
+  all shown" after filtering, and act on them at once —
+  - **Send a message** by email or WhatsApp, as an event update to the person who registered
+    (placeholders as on Email attendees);
+  - **Mark paid** — records what each still owes, by cash, EFT, card or other; paid registrations get
+    their tickets by email, as with a single payment;
+  - **Move to another ticket** (one event) — the same lines, issued tickets and QR codes move with
+    them, repriced at the new ticket's current price, so the difference shows as owing or overpaid;
+    places on the new ticket are checked first;
+  - **Put in a room or group** (one event) — their named people, with the group's capacity and
+    gender rules;
+  - **Export to Excel** (recorded in the access log, like other exports);
+  - **Cancel** — coupon uses released and the waitlist offered the places; no refund (record refunds
+    on the Payments page).
+  Each runs the same code as doing it one at a time (closed events, payment caps, coupons,
+  waitlist, privacy rules on messages), with a result per registration. Up to 500 at a time.
+- `POST /api/registrations/bulk` (campus-checked for every registration; payments and ticket moves
+  refused in licence read-only mode); `registrationIds` filter on the email and WhatsApp attendee
+  endpoints. Audit action `registrations_bulk` (migration `20261028170000_registrations_bulk`).
+
+## [1.49.0] - 2026-10-28
+
+### Added
+
+- **Today on the dashboard** (staff, supervisors, admins): what's on today — each event, or its
+  session today — with people checked in so far against places, children in now at kids church,
+  and volunteers here against rostered (and how many short). Supervisors and admins also see money
+  in today and over the last 7 days. Refreshes every 30 seconds; follows campus scoping.
+- **Waiting for you** (supervisors, admins): what needs someone, each linking to where it's dealt
+  with — unpaid registrations for events in the next two weeks, young people waiting for parental
+  consent, waitlists, cover requests, serving roles in the next week short of people, and for
+  admins past events to cash up, provider payments to reconcile, open privacy requests and failed
+  webhook deliveries.
+- **Command palette — Ctrl K (⌘K)** anywhere in the dashboard, or "Search or jump to…" on the
+  dashboards: pages, settings tabs and reports for the person's role, actions ("New event", "Scan
+  tickets", "Record a payment"…), and search — events for everyone; payments by amount ("R450") for
+  supervisors; people and registrations (by reference) for admins. Keyboard: ↑/↓, Enter, Esc.
+- Deep links: `/dashboard/supervisor/events?edit=<id>` and `?new=1`; `/dashboard/admin/registrations?q=&status=&event=`;
+  `/dashboard/admin/users?q=`.
+- `GET /api/dashboard/today`, `GET /api/dashboard/search?q=`.
+
+## [1.48.2] - 2026-10-28
+
+### Added
+
+- **Four demo seeds**, to match the church a demo is for — `npm run demo:small`, `demo:events`
+  (the original demo), `demo:ministry` and `demo:multicampus` from the repo root (`demo:list`
+  describes them; in `backend/` it's `npm run set-demo -- --profile=<name>`). New in the seeds:
+  multi-session courses with attendance and certificates, a "pick your days" conference, kids church
+  with families, children, rooms and check-ins (including some checked in right now), volunteer
+  rosters with QR check-ins and a cover request, an event series with followers and a season pass,
+  and three campuses with campus-limited staff. Campuses are switched on only for `multicampus`.
+  Series announcements and volunteer reminders are marked as sent, so the jobs don't email demo
+  people. See `backend/DEMO_DATA.md`.
+
+### Fixed
+
+- **`npm run set-demo` failed since 1.43.0** ("Event_createdById_fkey"): clearing the `Campus` table
+  with TRUNCATE … CASCADE also emptied `User` (it points at Campus for the home campus), deleting the
+  admin it keeps. Tables that `User` points at are now emptied with DELETE after the admin's links
+  to them are cleared.
+
+## [1.48.1] - 2026-10-28
+
+### Changed
+
+- **Built-in privacy notice brought up to date** with volunteer rosters (what is kept, reminders,
+  who sees the roster and cover requests), following an event series, season passes, webhooks
+  (connected systems, what they receive, 30-day copies), how people agree to the notice, and the
+  `cross_events_dismissed_notices` browser-storage item. Sites that haven't published their own
+  version show the new text straight away.
+- **Sites that published their own version** are now told: Admin → Privacy → Privacy notice lists
+  what changed in the built-in text since they last reviewed it, marks each section with new text
+  (**show it** / **Use the new text**), offers **Use all the new text**, and **Add** for built-in
+  sections the notice doesn't have. **Done — hide this** records the review
+  (`privacy_notice_builtin_reviewed`). Their own text is never changed without them; publish (with
+  "Significant change" if people should accept again) to make it live.
+
+### Fixed
+
+- **Agreeing to the notice when an account was made for you** — activating an account (made by
+  staff, at the door or by whoever registered you) now asks you to agree to the Terms of Use and
+  Privacy Policy, as sign-up does (consent log source "Account activation").
+- **Never accepted?** Anyone who has never accepted any version (accounts made for them, or from
+  before acceptances were recorded) is asked once after login ("Our privacy notice"), even while
+  the built-in notice is in use. Before, they were only asked after a version marked as a
+  significant change was published.
+- The "Change my cookie choice" button on the privacy page also shows above a cookie section an
+  admin wrote themselves (any section whose id mentions cookies), not only the built-in one.
+
+## [1.48.0] - 2026-10-28
+
+### Added
+
+- **Outbound webhooks** — Site settings → **Webhooks**: send what happens here to other systems
+  (ChurchSuite, Planning Center, Google Sheets through Zapier or Make…). Add an https address and
+  choose what to send: `registration.created`, `registration.paid`, `registration.cancelled`,
+  `payment.received`, `payment.refunded`, `ticket.checked_in`, `user.created`, `event.published`.
+- Each message is JSON `{ id, type, createdAt, data }` signed with the webhook's own secret
+  (`X-CrossEvents-Signature: t=…,v1=…`, HMAC-SHA256 of `<t>.<body>`; shown once, "New secret" to
+  rotate). **Send test**, a **delivery log** (30 days, with the full message and what came back) and
+  **Resend**. Failures are retried after 1 min, 5 min, 30 min, 2 h and 12 h, then marked failed.
+- Events are noticed in one place (a Prisma client extension in `config/db.js`), so every way of
+  registering, paying, cancelling, refunding or checking in is covered; each is checked again a
+  moment later, so a change that was rolled back sends nothing.
+- Safety and privacy: https addresses on public networks only (checked again at each send;
+  redirects aren't followed); each webhook is added to the POPIA operator register (marked inactive
+  when deleted); kids check-in and volunteer tickets are never sent; deliveries are deleted after 30
+  days and with an anonymised account.
+- New `webhooks` job (every minute, `WEBHOOKS_JOBS_ENABLED`); `WEBHOOKS_ENABLED=false` stops
+  noticing events. Audit action `webhook_endpoint_changed` (migration `20261028160000_webhooks`).
+
+## [1.47.4] - 2026-10-28
+
+### Fixed
+
+- **Update requested, then a newer version came out** — the Licence page said the newer version
+  was requested ("Version 1.47.3 is available. Update requested …") when the request was for an
+  older one, and there was no way to ask for the newer version; the update banner stayed hidden.
+  Now it shows the request ("You asked for version 1.47.0 on …") and, below it, that a newer
+  version has come out with **Ask for 1.47.3 instead** (Withdraw request stays). The banner shows
+  again and says to change the request. Changing it is audited as `hub_update_requested` with
+  `changedFrom`.
+- With Cross Events Hub 1.5.0 the Hub moves the open request on to the new version and emails the
+  provider once; with an older Hub the site withdraws the request and makes it again.
+
+## [1.47.3] - 2026-10-28
+
+### Added
+
+- **Season passes** — one price for a ticket at each of several events in a series. On the Event
+  series page supervisors make a pass (name, price, optional sale end) and tick which events and
+  which ticket (and variant) at each it includes; the form shows what they'd cost separately. Youth
+  (parental consent) events, staff-only tickets and per-session tickets can't be on a pass. Events
+  and price are fixed once someone has bought it (switch it off instead); campus-scoped supervisors
+  can only use their campuses' events.
+- **Buying** — on the series page signed-in people choose how many and buy: they're registered at
+  every event on the pass at once and pay once (a free pass gives the tickets straight away). If
+  online payment isn't possible the places stay booked and "Your passes" offers **Pay now**. A pass
+  stops selling when its first event starts.
+- **Money per event** — the price is split over the events in proportion to their normal ticket
+  prices (whole cents). Each registration's line is priced at its event's share, and the payment is
+  recorded as one payment per event (all linked to the purchase), so each event's cashup and reports
+  count only its part. Pass registrations aren't repriced by early-bird changes, take no coupon
+  codes, and their tickets can't be edited.
+- `/api/season-passes` (list, create, change, delete; `:id/buy`; `purchases/:id/checkout`; `mine`),
+  `passes` on `GET /api/series/by-slug/:slug`. Making, changing and buying passes is blocked in
+  licence read-only mode. Purchases are in "Download my data". Audit action `season_pass_changed`
+  (migration `20261028150000_season_pass`).
+
+## [1.47.2] - 2026-10-28
+
+### Added
+
+- **Series: year on year** report (Reports → Other) — pick a series and see each of its events side
+  by side, oldest first: registrations (not cancelled), tickets, income (as on the dashboard: refunds
+  counted, donations applied to orders left out) and people checked in (a multi-session event shows
+  the average per session), with the attendance rate and the change from the event before. Bar charts
+  of registrations and income; exports to PDF, Excel, email and WhatsApp like the other reports.
+  Campus-scoped staff see only their campuses' events. **Compare** on each series on the Event series
+  page opens it (`?report=seriesComparison&series=<id>`).
+- `GET /api/series/:id/compare`.
+
+## [1.47.1] - 2026-10-28
+
+### Added
+
+- **Event series** — group separate events (Camp 2025, Camp 2026; the monthly men's breakfast) on
+  one page. Supervisors make series on the new **Event series** page (name, web address,
+  description, picture) and put an event in one with the **Series** box in the event editor; a
+  copied event keeps its series. A series can have events at several campuses.
+- **Series page** `/series/<slug>`: what's coming up (event cards) and past events. Each event in a
+  series shows "Part of …" and **Next in this series** on its page.
+- **Follow a series** — signed-in people follow on the series page. When a new event in the series
+  goes live (and hasn't started) followers get one email, sent as News & announcements: only to
+  people opted in to news, with the unsubscribe link and one-click headers. New `series` job every
+  15 minutes (`SERIES_JOBS_ENABLED`); an event moved into another series is announced to that
+  series' followers.
+- Followed series are in "Download my data" and removed when an account is anonymised.
+- API: `/api/series` (list, create, change; delete for admins; `by-slug`; follow/unfollow),
+  `seriesId` on event create/update, `?series=<slug>` on `GET /api/events`, `series` and
+  `nextInSeries` on `GET /api/events/:id`. Creating and changing series is blocked in licence
+  read-only mode. Audit actions `series_created`, `series_updated`, `series_deleted` (migration
+  `20261028140000_event_series`).
+
+## [1.47.0] - 2026-10-28
+
+### Added
+
+- **Copy an event** — "Copy" on each card on the Events page opens the event editor filled in from
+  that event: details, campus, sessions, ticket options, variants and early-bird tiers, sections,
+  the registration form, notification recipients, the feedback questions, certificates and session
+  reminders. Everything can be changed before saving. A **New start** box at the top moves every
+  date by the same amount — the end, the sessions, the registration deadline, early-bird deadlines
+  and the feedback date. On save the event's allocation groups (rooms, buses, teams) are copied
+  too, and for admins its planned costs (a cost on a ticket option goes to the option with the
+  same name). Not copied: registrations, coupons, attachments, bundles, the short link, the go-live
+  time, cancelled sessions, kids check-in (kids ticket and rooms) and volunteer roles.
+- `POST /api/events/:id/copy-from` (blocked in licence read-only mode, campus-checked for both
+  events); `POST /api/events` takes `clonedFromId`, recorded in the `event_created` audit entry.
+
+## [1.46.2] - 2026-10-28
+
+### Added
+
+- **What's new before you update** — Site settings → Licence shows the release notes for every
+  version newer than the site, so you can decide whether to ask for the update. Updates that fix a
+  security problem or a serious bug are marked, and show as a red banner.
+- **Withdraw request** — changed your mind after pressing Request update? Withdraw it on the Licence
+  page and your provider is told not to update the site.
+- **Not now** — on the update banner or the Licence page: hides the "update available" reminder until
+  the next version comes out ("Remind me again" turns it back on). Urgent updates can't be put off.
+- **Notices from your provider** — planned maintenance and other messages from your provider show as
+  a banner at the top of the dashboard for site admins and supervisors, at the times given. Close
+  one with ×; current notices are also listed on the Licence page.
+
+- **`WHATS-NEW.md`** — the release notes churches see, in plain language. The Hub reads it from git
+  with the version tags, so a release needs its section there before tagging.
+
+Needs Cross Events Hub 1.4.0 for the notes, withdrawing and notices; with an older Hub the site
+works as before.
+
+## [1.46.1] - 2026-10-28
+
+### Removed
+
+- The Gitea CI workflow (`.gitea/workflows/ci.yml`). There's no Actions runner, so every push
+  left a run stuck on "Waiting". Tests and lint are run by hand before a release, and releases
+  are deployed with `scripts/deploy.sh` on the server.
+
+## [1.46.0] - 2026-10-28
+
+### Added
+
+- **Volunteer rosters** — plan who serves where (Supervisor → **Volunteer rosters**).
+  - **Serving roles** (Welcome, Parking, Kids, Sound…) per event, or per session on a multi-session
+    event, with the number of people needed, optional shift times and a short description. Each
+    event or session has its own roster; nothing repeats by itself.
+  - **Anyone with an account can volunteer:** My account → **Serving** lists events looking for
+    people and lets you sign up for a role that isn't full. Supervisors can also put someone on a
+    role (even beyond the number needed). Nobody can be in two roles at the same time. Supervisors
+    get a sign-up link to share (it works for hidden events too).
+  - **Reminders** by WhatsApp or email the day before a shift.
+  - **"Can't make it" swaps:** the volunteer asks for cover, the event's other volunteers are told,
+    and the first to accept takes the place straight away — no approval. The event's notification
+    recipients get an email about every swap and every withdrawal.
+  - **Check-in on the day:** volunteers scan the event's check-in QR code (show it on a screen or
+    print it) with their phone camera and are checked in for that day's shifts; staff can tick
+    people in on Staff → **Volunteers**, and undo it.
+  - **Kids rooms:** a role can be linked to a kids room. Its volunteers count as leaders on duty
+    in that room once they check in (for the room's ratio), and the room screen lists who is
+    rostered but not in yet.
+  - **Free volunteer ticket**, off by default: choose a ticket per event (or add a free
+    "Volunteer" ticket) and everyone on the roster gets a free place on it unless they already have
+    a ticket. It's given back when they leave the roster.
+  - **Roster sheet** with phone numbers, check-in times and a printable view; fill rate per
+    event; **hours served** per person across events.
+  - Audit log entries for the volunteer ticket, role changes, people put on or taken off a roster
+    and check-ins by hand; opening a roster is in the access log. "Download my data" includes
+    your shifts; anonymising an account gives up its future shifts.
+  - Background job `volunteers` (every 15 minutes, `VOLUNTEER_JOBS_ENABLED`) sends the reminders.
+
+### Fixed
+
+- **The kids check-in ticket was offered publicly:** the free "Kids check-in" ticket from 1.45.0
+  showed on the event page and could be booked by anyone. It (and the new volunteer ticket) is now
+  left out of public event pages and lists and refused on public registration; staff still see it.
+
+## [1.45.1] - 2026-10-28
+
+### Fixed
+
+- **Privacy notice (built-in text)** brought up to date: kids check-in (what's kept about
+  children and authorised adults, who sees allergies, medical and custody notes, pickup codes,
+  offline desk lists, the 6-month deletion), multi-session attendance, session reminders,
+  certificates and their public check, home campus, WhatsApp sign-in codes, and campus-limited
+  staff. "Stored on South African servers" is replaced by where the data really is: the site's
+  own database at the hosting provider in the operator list. It now also says what the site sends
+  Cross Code's licence server (health and totals, income as a range — no personal information),
+  and lists the kids check-in browser storage.
+  Sites that have already published their own notice keep it: review the changes and publish a
+  new version from Admin → Privacy → Privacy notice.
+- **Terms of use:** a new "Kids Check-in" section (pickup codes, parents' responsibility for
+  their children's details), sessions and certificates, kids messages among the required
+  messages, and account deletion from the Privacy page. Later sections are renumbered.
+
 ## [1.45.0] - 2026-10-28
 
 ### Added

DEPLOYMENT.md

@@ -56,7 +56,7 @@ curl -fsSLO https://c-git.crosscode.co.za/joshua/hope-events/raw/branch/main/scr
 sudo bash install.sh --domain events.yourchurch.org --no-ssl --version v1.41.2
 ```
 
-It installs Node 20, PostgreSQL, PM2 and nginx, creates the database, writes the config, builds
+It installs Node 24 LTS, PostgreSQL, PM2 and nginx, creates the database, writes the config, builds
 and starts the app (in `/opt/hope-events`, run by the `hopeevents` user). Use `--name`, `--dir`,
 `--web-port` and `--api-port` if other apps already use those names or ports; adjust the ports
 below to match.
@@ -305,28 +305,29 @@ cd /opt/hope-events
 sudo -u hopeevents -H bash scripts/deploy.sh v1.41.2     # or no tag for the latest main
 ```
 
-It backs up the database, checks out the release, installs, migrates, builds and reloads PM2,
+It backs up the database, checks out the release, installs, migrates, builds (the backend too,
+since 1.51.0) and reloads PM2,
 and goes back to the previous version if anything fails first. `backend/.env`,
 `frontend/.env.production`, `ecosystem.config.js` and the nginx/frpc configs are not in git, so
 updates keep your changes from this guide.
 
-### Deploying from CI over SSH
+### Upgrading Node
 
-The Gitea workflow deploys on a `v*` tag by SSHing to `DEPLOY_HOST`. Behind frp, that needs an
-SSH tunnel too, e.g. in `frpc.ini`:
+Node 20 stopped getting security fixes in April 2026; Cross Events runs on Node 24 LTS (supported
+until April 2028). `deploy.sh` warns when a server is still on an older Node. To upgrade:
 
-```ini
-[hope-events-ssh]
-type = tcp
-local_ip = 127.0.0.1
-local_port = 22
-remote_port = 6022
+```bash
+node -v                                                   # what you have now
+curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash -
+sudo apt-get install -y nodejs                            # replaces the old Node
+sudo npm install -g pm2                                   # PM2 for the new Node
+cd /opt/hope-events
+sudo -u hopeevents -H pm2 update                          # restart PM2's daemon on the new Node
+sudo -u hopeevents -H bash scripts/deploy.sh v1.51.4      # reinstall packages and rebuild for Node 24
 ```
 
-Then use the VPS as `DEPLOY_HOST`. The workflow's `ssh` call (`.gitea/workflows/ci.yml`) doesn't
-take a port yet, so add `-p 6022` there (or a `DEPLOY_PORT` secret) before relying on it. Only
-open this if you need it: it exposes this server's SSH on the VPS. Use key-only login. Deploying
-by hand (above) needs none of this.
+Use the version you're on (or a newer one) in the last line — the deploy reinstalls every package
+and rebuilds, which a Node upgrade needs.
 
 ## Troubleshooting
 

FEATURES.md

@@ -29,14 +29,17 @@ WhatsApp · PM2 for process management · optional Sentry for error monitoring.
 13. [Cashup & event costs](#cashup--event-costs)
 14. [Reports](#reports)
 15. [Site settings & setup wizard](#site-settings--setup-wizard)
-16. [Multi-campus](#multi-campus)
-17. [Kids check-in](#kids-check-in)
-18. [Accounts & security](#accounts--security)
-19. [Privacy (POPIA)](#privacy-popia)
-20. [Help system](#help-system)
-21. [Background jobs](#background-jobs)
-22. [Operations](#operations)
-23. [Page map](#page-map)
+16. [Event series](#event-series)
+17. [Multi-campus](#multi-campus)
+18. [Kids check-in](#kids-check-in)
+19. [Volunteer rosters](#volunteer-rosters)
+20. [Accounts & security](#accounts--security)
+21. [Privacy (POPIA)](#privacy-popia)
+22. [Accessibility](#accessibility)
+23. [Help system](#help-system)
+24. [Background jobs](#background-jobs)
+25. [Operations](#operations)
+26. [Page map](#page-map)
 
 ---
 
@@ -89,6 +92,14 @@ Feedback → Attendance**.
 - **Basic details** — title, description, start/end dates, registration
   deadline, picture (upload or URL), location (defaults to the org's address),
   contact person.
+- **Copy an event** — "Copy" on an event card opens the editor filled in from that
+  event (details, campus, sessions, options, variants, early birds, sections, form,
+  notification recipients, feedback questions, certificates, reminders). Setting
+  the **New start** moves every date with it (end, sessions, registration deadline,
+  early-bird deadlines, feedback date). Allocation groups are copied on save, and
+  for admins the planned costs (matched to options by name). Not copied:
+  registrations, coupons, attachments, the short link, the go-live time, kids
+  check-in and volunteer roles.
 - **Contact-only events** — for things like baptisms: shown publicly with a
   "Contact us" popup instead of registration, with no tickets.
 - **Multi-day events (sessions)** — one event on several dates, e.g. every
@@ -397,14 +408,31 @@ logout controls. Disconnected sessions are recovered automatically.
   and print an event's tickets.
 - **Kids check-in** (`/dashboard/staff/kids`) and the **room screen**
   (`/dashboard/staff/kids/rooms`) — see [Kids check-in](#kids-check-in).
+- **Volunteers** (`/dashboard/staff/volunteers`) — today's roster, ticking volunteers in and the
+  check-in QR code — see [Volunteer rosters](#volunteer-rosters).
 
 ---
 
 ## Supervisor tools
 
-- **Dashboard** — KPIs (active events, revenue, donations, registrations,
-  tickets sold, each vs. the previous month), revenue trend chart, top events,
-  and recent scans. Tiles link to the matching report.
+- **Choosing an event** (staff and supervisor pages: scanner, event tickets, at the door, payments,
+  manual registration, email and WhatsApp, forms, attendance, consent, waitlist, allocations,
+  bundles, offline scans, kids and volunteer set-up, manage registrations, kiosk): a searchable
+  picker instead of a long dropdown. It opens on upcoming events, soonest first; **Show past
+  events** lists past ones (latest first), and typing searches every event by name, campus or date.
+  Arrow keys, Enter and Escape work. `components/shared/EventPicker.tsx`.
+- **Dashboard** — **Today** (each event or session on today: checked in so far
+  against places, children in now, volunteers here; money in today and this
+  week) and **Waiting for you** (unpaid registrations for the next two weeks,
+  parental consent outstanding, waitlists, cover requests, roster gaps; for
+  admins also cashups due, payments to reconcile, privacy requests, failed
+  webhooks — each links to where it's dealt with); then KPIs (active events,
+  revenue, donations, registrations, tickets sold, each vs. the previous month),
+  revenue trend chart, top events, and recent scans. Staff see Today too.
+- **Command palette (Ctrl K / ⌘K)** — anywhere in the dashboard: pages, settings
+  and reports for the role, actions ("New event", "Scan tickets"…), and search:
+  events; payments by amount ("R450") for supervisors; people and registrations
+  for admins. Follows campus scoping.
 - **Manage events** — the 9-step event wizard, ticket options, variants,
   sections, form and attachments.
 - **At the door** — search by name/phone/ticket ID, walk-in registration,
@@ -455,12 +483,20 @@ logout controls. Disconnected sessions are recovered automatically.
   [Privacy](#privacy-popia)).
 - **Registrations** — all registrations, with filters (event, status, text),
   status counts, revenue and outstanding totals, and per-registration options,
-  form answers and payments (with who recorded each one).
+  form answers and payments (with who recorded each one). **Bulk actions** on
+  ticked registrations (or all shown): message (email/WhatsApp), mark paid
+  (records the balance by method), move to another ticket (same tickets and QR
+  codes, repriced), put in a room or group, export to Excel, cancel — each
+  through the same rules as one at a time, with a result per registration.
+- **Saved filters** — on Manage registrations, Users, Events and Reports: name the
+  current filters, apply one with a click, star one as the default for the page
+  (not applied over a deep link). Per person, on the server.
 - **Cashup** — see below.
 - **Audit log** (`/dashboard/admin/audit-log`) — who did what and when for
   refunds, donation assign/unassign, manual registrations, staff
   cancellations, event create/update/delete, settings changes, and coupon codes
-  (created, edited, turned off, applied or removed by staff).
+  (created, edited, turned off, applied or removed by staff), and every later feature's admin
+  actions. Search by person, target or IP; filter by action, role and dates; 50 a page.
 - **Site settings** — see below.
 
 ---
@@ -486,7 +522,7 @@ logout controls. Disconnected sessions are recovered automatically.
 
 ## Reports
 
-A full-width workspace with shared filters (events, date range with presets,
+A full-width workspace with shared filters (events, searchable, with "Select these N" for the matches; date range with presets,
 include past/inactive/closed) and a searchable grid of reports, each opening in
 a viewer with its own filters, stat tiles and bar charts.
 
@@ -497,6 +533,7 @@ a viewer with its own filters, stat tiles and bar charts.
 | Ticketing | Ticket usage summary |
 | Donations | Donations breakdown (used / unused per event, plus the sponsorship pool) |
 | Cashup | Cashup reconciliation · Cashup audit trail |
+| Other | Series: year on year (a series' events side by side — registrations, tickets, income, checked in, attendance rate, change from the one before) |
 
 **Export:** Print, branded PDF download, styled Excel (`.xlsx`) workbook,
 Email (to yourself), or WhatsApp (the PDF to your own number). Dashboard tiles
@@ -516,7 +553,7 @@ applied without a restart. Secrets are encrypted with AES-256-GCM.
 |-----|----------|
 | Organisation | Name, tagline, contact email/phone, address (with map link) |
 | Campuses | Off by default. Turn on, then add, order, archive or delete campuses (name, web address, address, contact, colour, logo, default event location, daily-summary recipients) |
-| Branding | Primary/secondary/accent colours, logo, favicon, colours suggested from the logo, live website/email preview on desktop and mobile |
+| Branding | Primary/secondary/accent colours (with a readability warning and a darker shade offered when the primary is too light), logo, favicon, colours suggested from the logo, live website/email preview on desktop and mobile |
 | Notifications | Registrations inbox and admin notification emails |
 | Email | SMTP host/port/TLS/user/password/from, with a "Test connection" button |
 | Legal | Operator, Information Officer, website, effective date for the Terms/Privacy pages |
@@ -528,6 +565,33 @@ See [SETTINGS.md](./SETTINGS.md) for the default of every setting.
 
 ---
 
+## Event series
+
+Separate events grouped on one page — every year's camp, the monthly men's breakfast (each event
+keeps its own registrations; for one event on several dates see multi-day events).
+
+- **Event series** page (supervisors): name, web address (`/series/<slug>`), description, picture;
+  each series lists its events (campus-scoped supervisors see only their campuses' events in it)
+  and its number of followers. Admins can delete a series (its events stay).
+- **Series box** in the event editor's Basic details. A copied event keeps its series. A series can
+  have events at several campuses.
+- **Public series page**: upcoming events as cards, then past events. Event pages in a series show
+  "Part of …" and **Next in this series** (the next public event in it).
+- **Follow a series**: signed-in people follow on the series page; when a new event in it goes live
+  (before it starts) they get one email, sent as News & announcements (opted-in only, with an
+  unsubscribe link). The `series` job runs every 15 minutes.
+- **Year on year**: Reports → Series: year on year (or **Compare** on the Event series page)
+  compares the series' events — registrations, tickets, income, checked in (average per session on
+  multi-session events), attendance rate — each against the one before.
+- **Season passes**: on the Event series page, a pass gives a ticket (and variant) at each event
+  ticked, at one price (optional sale end; stops when its first event starts; no youth events,
+  staff-only or per-session tickets). Buyers choose how many on the series page and are registered at
+  every event at once with one payment (or tickets at once when free; "Pay now" later if online
+  payment isn't possible). The price is split over the events in proportion to their normal prices;
+  each event gets its own registration line and payment for its share, so cashups stay per event.
+  Pass registrations aren't repriced, take no codes and can't be edited. Events and price lock once
+  sold.
+
 ## Multi-campus
 
 For a church with several campuses in one install (Site settings → Campuses, off by
@@ -594,6 +658,43 @@ label printers.
   changed only by parents, supervisors and admins (audited); opening the desk/room screens and
   offline downloads are in the access log; a child's profile is deleted after **6 months** without
   a check-in (Admin → Privacy → Retention).
+- **Volunteers in kids rooms:** a serving role linked to a room puts its volunteers on duty there
+  when they check in; the room screen lists who is rostered but not in yet.
+- The kids ticket is never offered publicly (left out of public event pages, refused on public
+  registration).
+
+---
+
+## Volunteer rosters
+
+Who serves where, for an event or each session.
+
+- **Roles** (Supervisor → Volunteer rosters, `/dashboard/supervisor/volunteers`): name, people
+  needed, optional shift times (default: the session's or event's times), description, and
+  optionally a kids room. On a multi-session event each role is for one session. A role can't be
+  deleted once someone has checked in for it.
+- **Volunteering** (My account → Serving, `/dashboard/user/serving`): anyone with an account signs
+  up for a role that isn't full; supervisors can also put people on (beyond the number needed).
+  Nobody can be in two roles whose shifts overlap. `?event=<id>` opens one event (the sign-up link
+  supervisors share, also for hidden events). Volunteers are told when they're put on, taken off,
+  or a role is deleted, and get a **reminder the day before**.
+- **Swaps:** "Can't make it" asks for cover — the event's other volunteers are told and the request
+  shows on everyone's Serving page; the first to accept takes the place at once (no approval). The
+  event's notification recipients (or its creator) are emailed about every swap and withdrawal.
+- **Check-in:** volunteers scan the event's **check-in QR code** (Check-in QR tab, or Staff →
+  Volunteers) with their phone camera → `/serve/check-in` → every shift of theirs on that day is
+  checked in. Staff can tick people in by hand (and undo). Check-in opens on the day of the shift
+  and closes when it ends.
+- **Kids rooms:** checking in for a role linked to a kids room puts the volunteer on duty in that
+  room (counted for the ratio, like "I'm on duty"); undoing the check-in takes them off.
+- **Volunteer ticket** (off by default): choose a main ticket of the event, or add a free
+  "Volunteer" ticket. Volunteers without a ticket get a free place on it (in My Events); it's
+  cancelled when they leave the roster (unless it was scanned), moves with a swap, and is never
+  offered publicly.
+- **Reports:** roster sheet (phone numbers, check-in time and how), printable; fill rate per event;
+  **hours served** per person (checked-in shifts × shift length) over all events or one.
+- **Read-only licence:** new roles and sign-ups are blocked; check-ins, swaps and withdrawals keep
+  working.
 
 ---
 
@@ -652,8 +753,12 @@ and published, numbered versions (earlier ones stay readable with `?version=N`).
 Placeholders (`{org}`, `{ioName}`, `{ioEmail}`, `{website}`, `{orgEmail}`,
 `{medicalRetentionDays}`, `{operators}`) are filled in from Site settings and the
 operator register. A version marked as a significant change is accepted once by everyone
-after their next login; sign-up records the version accepted. The contact page shows the
-Information Officer.
+after their next login. People agree to the notice at sign-up and when they activate an account
+made for them; anyone who never has is asked once after login. When the built-in text changes
+in an update, a site with its own published version sees what changed in the editor, with each
+changed section marked (**Use the new text**, **Use all the new text**, **Add** missing sections,
+**Done — hide this**). The "Change my cookie choice" button shows above the cookie section. The
+contact page shows the Information Officer.
 
 **Registers and logs** (same admin page):
 
@@ -676,7 +781,7 @@ Information Officer.
   and the people affected were told, and drafts of both notifications.
 - **Readiness** — a scored checklist of what's set up, each item linking to its fix.
 
-**For admins** — **Data requests** (`/dashboard/admin/data-requests`): correction and
+**For admins** — **Data requests** (`/dashboard/admin/data-requests`, searchable, closed ones paged): correction and
 deletion requests with a 30-day due date, emailed to the Information Officer and
 admins, reminded daily when due within a week. Completing a deletion anonymises the
 person: name, contact details, the people they registered, form answers, consent
@@ -687,6 +792,18 @@ log.
 
 ---
 
+## Accessibility
+
+Built to WCAG 2.2 AA on the public pages, sign-in, registration, payment, My Events and the
+self-service kiosk (1.50.0): "Skip to main content" link, visible keyboard focus, labelled fields,
+named buttons (ticket quantities say "Add one …"), errors announced as they appear, popups that
+trap focus and close with Escape, readable contrast with underlined in-text links, and "reduce
+motion" respected. Branding warns when the primary colour is too light for white text and
+suggests a darker shade. axe-core checks and keyboard tests in the e2e suite
+(`e2e/accessibility.spec.ts`) keep it that way.
+
+---
+
 ## Help system
 
 A floating **"Need help?"** button on every page opens a page-specific guide
@@ -695,6 +812,27 @@ falling back to a general guide.
 
 ---
 
+## Outbound webhooks
+
+Site settings → **Webhooks** (admins): send what happens to other systems as it happens.
+
+- **Endpoints**: name, https address, and the event types to send — registration created / paid /
+  cancelled, payment received / refunded, ticket checked in, account created, event published.
+  Switch off, edit, delete, **Send test**, **New secret**.
+- **Messages**: JSON `{ id, type, createdAt, data }` (registration with items and totals, payment,
+  check-in with session, person, event); headers `X-CrossEvents-Event`, `X-CrossEvents-Delivery` and
+  `X-CrossEvents-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<body>">` with the endpoint's secret.
+- **Delivery log** per endpoint (30 days): status, tries, response code or error, the full message,
+  **Resend**; filter by status and **Load older**. Retries after 1 min, 5 min, 30 min, 2 h, 12 h, then failed.
+- Every path that registers, pays, cancels, refunds or checks in is covered (Prisma client
+  extension); rolled-back changes send nothing. Kids check-in and volunteer tickets are never sent.
+- https and public addresses only (DNS checked at each send, redirects not followed). Each endpoint
+  is added to the operator register; deliveries are deleted after 30 days and with an account.
+- **How webhooks work** (1.50.2), a guide on the tab (open until the first webhook is added): the
+  envelope and headers, retries and duplicates, checking the signature (Node.js and PHP examples),
+  Zapier/Make set-up, and a copyable example message for every event type. The examples come from
+  `EVENT_TYPES[].example` in `utils/webhooks.js`; a test keeps them the same shape as what is sent.
+
 ## Background jobs
 
 Timed jobs run on a job queue in Postgres (pg-boss, `backend/src/jobs/index.js`): each
@@ -713,6 +851,9 @@ can't start, the same jobs run on in-process timers.
 | `payment-status` — look up PayFast checkouts (10 min – 3 days old) whose notification never arrived, and record them | Every 15 minutes (`PAYMENT_STATUS_JOB_ENABLED=false`) |
 | `feedback` — post-event feedback forms and their 3-day reminder | Every 15 minutes (`FEEDBACK_JOB_ENABLED=false`) |
 | `sessions` — session reminders, and certificates for events that ended in the last 14 days | Every 5 minutes (`SESSION_JOBS_ENABLED=false`) |
+| `volunteers` — volunteer reminders the day before a shift | Every 15 minutes (`VOLUNTEER_JOBS_ENABLED=false`) |
+| `series` — email a series' followers when a new event in it goes live | Every 15 minutes (`SERIES_JOBS_ENABLED=false`) |
+| `webhooks` — send webhook deliveries that are due, retry failures, delete deliveries after 30 days | Every minute (`WEBHOOKS_JOBS_ENABLED=false`) |
 | `consent` — parental consent reminders, and deleting medical details after events | 09:00 daily (`CONSENT_JOBS_ENABLED=false`) |
 | `privacy` — remind admins of privacy requests due within a week or overdue | 08:00 daily (`PRIVACY_JOBS_ENABLED=false`) |
 | `retention` — delete/anonymise personal information past its retention period (Admin → Privacy → Retention) | 03:30 daily (`RETENTION_JOBS_ENABLED=false`) |
@@ -733,8 +874,14 @@ can't start, the same jobs run on in-process timers.
   never switches it off: past the end date there's a grace period (banner for site admins only),
   then — or when suspended, revoked or not licensed — the site is read-only (events can't be
   created or edited; no new registrations or payments; tickets still scan, data can be exported).
-  The site checks in 30 seconds after starting and after a licence key is connected. Admins see when an update is available and press **Request update**,
-  which tells the provider through the Hub (the site never updates itself).
+  The site checks in 30 seconds after starting and after a licence key is connected. Admins see when an update is available, with
+  **what's new** in each version, and press **Request update**, which tells the provider through the Hub (the site never updates
+  itself). A request can be **withdrawn**; when a newer version comes out after asking, the page shows
+  the version asked for and **Ask for … instead** moves the request on to the newer one. **Not now** hides the update banner until the next version; urgent updates (security or
+  serious bug fixes) can't be put off and show a red banner.
+- **Notices from the provider** — maintenance and other messages the provider posts in the Hub show as a banner on the dashboard
+  for site admins and supervisors, in their time window; each can be closed (per browser) and stays listed on Site settings →
+  Licence. The provider can email them to the church too.
   See `docs/hub-protocol.md`.
 - **`/health`** — status, version, database, background jobs and last backup.
 - **PM2** (`ecosystem.config.js`) runs backend and frontend, restarting either
@@ -742,17 +889,24 @@ can't start, the same jobs run on in-process timers.
 - **Sentry** error monitoring when `SENTRY_DSN` / `NEXT_PUBLIC_SENTRY_DSN` are
   set.
 - Unhandled promise rejections are logged and don't crash the server.
-- Backend status page (`/`) and built-in API docs page (`/docs`).
+- Backend status page (`/`) and built-in API docs page (`/docs`); **API v2** (`/api/v2`, 1.51.0)
+  with one error shape, paged lists and an OpenAPI 3.1 reference at `/docs/v2` (admins). Public
+  events, my account and registrations, registering, cancelling and paying online (1.51.1),
+  signing up, logging in (with the 2FA step), changing my details and checking tickets in (1.51.2;
+  the scanner and at-the-door use it from 1.51.3); the frontend's v2 calls are typed from the
+  OpenAPI document. v1 endpoints with a v2 replacement send `Deprecation` and a `successor-version`
+  link (1.51.3).
+- **TypeScript backend** (1.51.0): `.ts` files are checked strictly, `.js` compiles as it is;
+  deploys build `dist/`, which `src/index.js` runs.
+- **Command palette** (Ctrl+K): every page, settings tab, report and quick action for your role.
 - **Tests** — Jest unit tests in `backend/tests` (`npm test`), and Playwright
   end-to-end tests in `e2e/` (`npm run test:e2e`) that start their own backend and
   frontend against a separate, freshly seeded database: public pages, free and paid
   registration through to check-in and cashup, multi-day check-in, the attendance
   register and certificates, the event wizard, the kiosk, and the admin jobs page.
-- **CI** — `.gitea/workflows/ci.yml` runs the backend tests, frontend lint/typecheck/
-  build and the end-to-end tests on every push (needs a Gitea Actions runner). A `v*`
-  tag also deploys over SSH with `scripts/deploy.sh` once the `DEPLOY_*` secrets are set:
-  it backs up the database, checks out the tag, migrates, builds and reloads PM2, and
-  goes back to the previous version if a step fails before the reload.
+- **Deploy script** — `scripts/deploy.sh [tag]`, run on the server, backs up the
+  database, checks out the release, migrates, builds and reloads PM2, and goes back to
+  the previous version if a step fails before the reload.
 - Versioning via git tags and [CHANGELOG.md](./CHANGELOG.md).
 
 ---
@@ -764,6 +918,7 @@ can't start, the same jobs run on in-process timers.
 | `/` | Public | Home |
 | `/events`, `/events/[id]` | Public | Event list and detail |
 | `/campus/[slug]` | Public | A campus's page and its events (while campuses are on) |
+| `/series/[slug]` | Public | A series' page: upcoming and past events, Follow |
 | `/[alias]` | Public | Event short link |
 | `/register/[eventId]` | Public / User | Registration |
 | `/registration/success` | Public / User | Confirmation, form and pay |
@@ -777,9 +932,10 @@ can't start, the same jobs run on in-process timers.
 | `/waitlist/claim/[token]` | Public | Claim a waitlist place |
 | `/certificates/verify/[code]` | Public | Check a completion certificate |
 | `/unsubscribe?t=…` | Public | Unsubscribe from news (link in news emails/WhatsApps) |
+| `/serve/check-in?code=…` | User (logs in first) | Volunteer check-in (where the event's check-in QR code leads) |
 | `/self-service` | Supervisor-unlocked | Kiosk |
 | `/set-banner` | Supervisor | Site banner |
-| `/dashboard/user` (+ `/payments`, `/donate`, `/forms`, `/profile`, `/privacy`, `/kids`, `/reset-password`) | User | My Events |
-| `/dashboard/staff` (+ `/ticket-scanning`, `/event-tickets`, `/my-groups`, `/kids`, `/kids/rooms`) | Staff | Staff tools |
-| `/dashboard/supervisor` (+ `/events`, `/event-options`, `/at-the-door`, `/manual`, `/manual-registration`, `/payments`, `/coupons`, `/waitlist`, `/attendance`, `/consent`, `/offline-scans`, `/allocations`, `/kids`, `/email-attendees`, `/whatsapp-attendees`, `/forms`, `/reports`) | Supervisor | Supervisor tools |
+| `/dashboard/user` (+ `/payments`, `/donate`, `/forms`, `/profile`, `/privacy`, `/kids`, `/serving`, `/reset-password`) | User | My Events |
+| `/dashboard/staff` (+ `/ticket-scanning`, `/event-tickets`, `/my-groups`, `/kids`, `/kids/rooms`, `/volunteers`) | Staff | Staff tools |
+| `/dashboard/supervisor` (+ `/events`, `/event-options`, `/at-the-door`, `/manual`, `/manual-registration`, `/payments`, `/coupons`, `/waitlist`, `/attendance`, `/consent`, `/offline-scans`, `/allocations`, `/kids`, `/volunteers`, `/email-attendees`, `/whatsapp-attendees`, `/forms`, `/reports`) | Supervisor | Supervisor tools |
 | `/dashboard/admin` (+ `/users`, `/registrations`, `/forms`, `/cashup`, `/cashup/[id]`, `/audit-log`, `/data-requests`, `/privacy`, `/settings`) | Admin | Admin tools |

README.md

@@ -92,9 +92,9 @@ Documentation: see Frontend README for environment and scripts.
     `E2E_DATABASE_URL` — which is dropped, recreated and seeded on every run. Your own dev
     servers and database aren't touched. The database user needs permission to create
     databases.
-- CI: `.gitea/workflows/ci.yml` runs all of the above on every push once a Gitea Actions
-  runner is registered. Pushing a `v*` tag also deploys with `scripts/deploy.sh` when the
-  `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY` (and optional `DEPLOY_PATH`) secrets are set.
+- There's no CI: run these yourself, plus `npx eslint .` in `frontend/`, before tagging a
+  release (the deploy's `next build` fails on any lint error). Releases are deployed by hand
+  with `scripts/deploy.sh` (see [DEPLOYMENT.md](./DEPLOYMENT.md)).
 
 ## Deployment
 
@@ -107,7 +107,7 @@ curl -fsSLO https://c-git.crosscode.co.za/joshua/hope-events/raw/branch/main/scr
 sudo bash install.sh --domain events.yourchurch.org --email you@yourchurch.org [--version v1.41.0]
 ```
 
-It installs Node 20, PostgreSQL (with its own database and a random password), PM2, nginx (the
+It installs Node 24 LTS, PostgreSQL (with its own database and a random password), PM2, nginx (the
 API, uploads, `/health` and `/docs` to the backend, everything else to the site) and an HTTPS
 certificate, writes `backend/.env` and `frontend/.env.production`, migrates, builds and starts the
 app. Then open `https://<domain>/setup`: create the admin account and enter the **licence key**

SETTINGS.md

@@ -23,7 +23,7 @@ in-process settings cache TTL) without a server restart.
 
 | Setting | Default when unset | Notes |
 |---|---|---|
-| `primary_color` | Legacy `accent_color` value if present, else `#4F46E5` (indigo) on the website / `#1e3a5f` (navy) in emails | See [Two different fallbacks](#two-different-fallbacks-for-primary_color) below — this is the one setting with a genuine inconsistency worth knowing about. Drives buttons, links, nav highlights, and the email header/CTA. |
+| `primary_color` | Legacy `accent_color` value if present, else `#4F46E5` (indigo) on the website / `#1e3a5f` (navy) in emails | See [Two different fallbacks](#two-different-fallbacks-for-primary_color) below — this is the one setting with a genuine inconsistency worth knowing about. Drives buttons, links, nav highlights, and the email header/CTA. The Branding tab warns when it is under 4.5:1 against white (too light for white text and links) and offers a darker shade (1.50.0). |
 | `secondary_color` | `210 40% 96.1%` background / near-black text (light gray "wash", shadcn's stock theme) | The Branding tab's color picker *pre-fills* `#8B5CF6` as a suggested starting point, but that's only a UI default — if you never hit Save, the actual site uses the light-gray fallback, not violet. |
 | `accent_color` | `210 40% 96.1%` background / near-black text (same light gray as Secondary) | Same story as Secondary — the picker pre-fills `#EC4899` (pink) as a suggestion only. |
 | `logo_url` | Bundled logo (`frontend/src/app/church_logo.jpg`) | Shown in the navbar. This is still the original Hope Family Church artwork checked into the repo — swap the file (or upload a real logo via the Branding tab) before deploying for a different organisation. |
@@ -116,6 +116,11 @@ Managed in the Payments tab (through `/api/payments/providers/settings` and `/ap
 | `PRIVACY_JOBS_ENABLED` (env) | `true` | The daily 08:00 `privacy` job that reminds admins of requests due within a week or overdue. |
 | `retention_policies` | Inactive accounts 60 months (on), form answers 12, login history 24, payment details 24, children at kids check-in (`kids_profiles`) 6, audit/access logs 60 — all on | Admin → Privacy → Retention (JSON `{ policies: { key: { enabled, months } }, reviewedAt, reviewedBy }`). Minimums: inactive accounts and logs 12 months, login history and payment details 3, form answers and kids profiles 1; maximum 240. Saving marks them reviewed (readiness check). |
 | `retention_last_run` | — | When the `retention` job last ran and what it did (readiness check: within 2 days). |
+| `VOLUNTEER_JOBS_ENABLED` (env) | `true` | The `volunteers` job (every 15 minutes) that sends volunteer reminders the day before a shift. |
+| `WEBHOOKS_JOBS_ENABLED` (env) | `true` | The `webhooks` job (every minute): sends deliveries that are due (retries), picks up sends cut off by a restart, deletes deliveries older than 30 days. New events are sent straight away without it. |
+| `WEBHOOKS_ENABLED` (env) | `true` | `false` stops noticing events for outbound webhooks altogether (nothing new is queued). |
+| `WEBHOOKS_ALLOW_PRIVATE` (env) | `false` | `true` lets webhook endpoints use http and private or local addresses — for local testing only (the e2e tests set it). |
+| `SERIES_JOBS_ENABLED` (env) | `true` | The `series` job (every 15 minutes) that emails a series' followers once when a new event in it goes live (News & announcements: only people opted in to news). |
 | `RETENTION_JOBS_ENABLED` (env) | `true` | The nightly 03:30 `retention` job. Off means nothing expires automatically. |
 | `wawp_webhook_last_seen` | — | Set when WAWP's webhook arrives with the right secret; the readiness page uses it to check WhatsApp STOP is set up. |
 | `privacy_notice_draft` | — | The unpublished draft from Admin → Privacy → Privacy notice (JSON). Published versions are in the `PrivacyNotice` table. With no published version the built-in notice (`backend/src/utils/privacyNotice.js`) is shown. The notice's org name, Information Officer, website, emails and medical retention days come from the settings above when it's shown. |

WHATS-NEW.md

@@ -0,0 +1,638 @@
+# What's new in Cross Events
+
+What each version changes for the church, in plain language. Churches see these notes on Site
+settings → Licence before they ask for an update, so they can decide whether they want it.
+
+<!--
+How this file is used: the Cross Events Hub reads it from main every 15 minutes, and shows a section
+only once its version is tagged (so write it before tagging; fixes to old sections show straight away). Each version is a "## 1.2.3" heading; add "— urgent" (or "security") to the heading for a
+security or serious bug fix, which churches can't put off. Under it, lines starting with "- " show as
+a list and other lines as paragraphs; **bold**, `code` and links are shown as plain text.
+Write for church admins, not developers: no environment variables, endpoints or job names. The
+developer log is CHANGELOG.md. A tagged version without a section here shows "No details given".
+-->
+
+## 1.51.8
+
+- **More groundwork for 2.0.** Event pages, ticket types, scanning sections, attachments, planned
+  costs and picture uploads now run on the new version of the server's connection to the app. They
+  work just as before.
+
+## 1.51.7
+
+- **More groundwork for 2.0.** Creating and editing events, and every list of events staff choose
+  from, now run on the new version of the server's connection to the app. They work as before.
+- The background job runner was updated. Its list of recent runs (Site settings → Background jobs)
+  starts afresh with this version.
+
+## 1.51.6
+
+- **Find anything with Ctrl+K.** The search box (Ctrl+K) now lists every report, and pages that
+  were missing: the dashboard, all reports, ticket options, your groups, and your own events,
+  payments, privacy, kids, serving, forms and donations.
+- Excel downloads use a newer, maintained library. They look the same.
+
+## 1.51.5
+
+- **Updated framework.** The site now runs on the latest version of its web framework. Nothing
+  changes in how it works.
+
+## 1.51.4 — security
+
+- **Security updates** to the parts the site is built on, including a critical fix in the web
+  framework. Recommended for everyone.
+
+## 1.51.3
+
+- **More groundwork for 2.0.** The ticket scanner and check-in at the door now run on the new version
+  of the server's connection to the app, and the server's web framework has been updated. They work
+  just as before.
+
+## 1.51.2
+
+- **More groundwork for 2.0.** Logging in, signing up and changing your details now run on the
+  new version of the server's connection to the app. They work just as before.
+
+## 1.51.1
+
+- **More groundwork for 2.0.** Registering, paying online and cancelling now run on the new
+  version of the server's connection to the app. They work just as before.
+
+## 1.51.0
+
+- **Groundwork for Cross Events 2.0.** Behind the scenes, the server is moving to a newer, safer
+  way of talking to the app, ready for the AI helpers in 2.0. Nothing changes in how you use
+  Cross Events.
+
+## 1.50.2
+
+- **Finding an event quickly.** Wherever staff and supervisors choose an event (the scanner, at
+  the door, payments, messages, forms, attendance and more) there is now a search box. The list
+  opens on upcoming events, past ones are one click away, and typing finds any event by name,
+  campus or date. The events list in Reports can be searched too.
+- **Webhook guide.** Site settings → Webhooks has a "How webhooks work" guide for whoever connects
+  another system: what is sent and when, how to check it came from you, and an example message for
+  every kind of event.
+
+## 1.50.1
+
+- **Finding things in long lists.** The audit log can be searched by person, what was changed or
+  IP address, filtered by role, and its action list now includes every kind of action. Data
+  requests can be searched and come a page at a time, and the webhook delivery log can show only
+  failed deliveries and load older ones.
+- **Fix:** the audit log's "To" date now includes that day.
+- **Faster Payments page** for churches with a few years of payments behind them.
+
+## 1.50.0
+
+- **Easier for everyone to use.** The public pages, registration, payment, My Events and the
+  self-service kiosk now work properly with a keyboard and with screen readers: a "Skip to main
+  content" link, a clear outline showing where you are, popups that can be closed with Escape, and
+  every form field, button and error message read out correctly. Faint grey text is darker and
+  links in sentences are underlined, so they're easier to read.
+- **Branding check.** If the main colour you pick in Site settings → Branding is too light for
+  white text to be readable, you'll see a warning and can switch to a darker shade with one click.
+
+## 1.49.2
+
+- **Saved filters.** On Manage registrations, Users, Events and Reports, save the filters you use
+  under a name and get back to them with one click. Star one and it's ready every time you open the
+  page. They're yours and follow you to any device.
+
+## 1.49.1
+
+- **Do many at once.** On Manage registrations, tick the people you want (or select everyone
+  shown after filtering) and send them a message, mark them paid, move them to another ticket, put
+  them in a room or group, export them to Excel, or cancel them.
+- Moving people to another ticket keeps their tickets and QR codes; the price follows the new
+  ticket, so any difference shows as owing.
+- You see what happened to each one, and anything that couldn't be done says why.
+
+## 1.49.0
+
+- **Today, at a glance.** The dashboard now starts with what's on today: each event with how many
+  people are checked in, children in at kids church, and volunteers here — plus money in today and
+  this week.
+- **Waiting for you.** One list of what needs someone — unpaid registrations, consent forms still
+  outstanding, waitlists, volunteers asking for cover, events to cash up — each a click away.
+- **Ctrl K to find anything.** Press Ctrl K anywhere in the dashboard to jump to a page or setting,
+  start "New event", or find an event, a payment by amount ("R450") or a person.
+
+## 1.48.2
+
+- No changes for churches in this version — it adds demo data for showing Cross Events to other
+  churches.
+
+## 1.48.1
+
+- **Privacy notice brought up to date** with volunteer rosters, event series, season passes and
+  webhooks. If you haven't published your own version, your site shows the new text straight away.
+- **Published your own version?** Admin → Privacy → Privacy notice now shows what changed in the
+  built-in text, section by section, so you can take the new wording with one click and publish.
+- **Everyone agrees to the notice once.** People whose account was made for them agree when they
+  activate it, and anyone who never has is asked once after they next log in.
+
+## 1.48.0
+
+- **Webhooks.** Connect Cross Events to other systems — ChurchSuite, Planning Center, a Google
+  Sheet through Zapier or Make. Choose what to send (new registrations, payments, check-ins, new
+  accounts, published events) in Site settings → Webhooks, and it goes out as it happens.
+- Every message is signed so the other system can trust it, failures are tried again
+  automatically, and a delivery log shows what was sent.
+- Each webhook is added to your operator register for POPIA. Children's details are never sent.
+
+## 1.47.4
+
+- **Asked for an update, and a newer one came out?** The Licence page now shows which version you
+  asked for, tells you when a newer one is out, and lets you ask for that one instead with one
+  button.
+
+## 1.47.3
+
+- **Season passes.** Sell a ticket for several events in a series at one price — say all of next
+  year's breakfasts. People buy it on the series page, pay once, and get a ticket for each event.
+- The money is shared out over the events in line with their normal ticket prices, so each event's
+  cashup shows its part.
+- Set passes up on the Event series page. A pass stops selling when its first event starts.
+
+## 1.47.2
+
+- **Compare a series year on year.** A new report puts the events in a series side by side —
+  registrations, tickets, income and how many came — with how much each went up or down from the
+  one before. Open it from Reports, or with **Compare** on the Event series page.
+
+## 1.47.1
+
+- **Event series.** Group events that come back — every year's camp, the monthly breakfast — on
+  one page that shows what's coming up and what's been. Each event in a series links to the next one.
+- **Follow a series.** People can follow a series and get an email when the next event in it is
+  out. It counts as news, so only people who chose to get news and announcements receive it.
+- A copied event stays in its series, and a series can have events at different campuses.
+
+## 1.47.0
+
+- **Copy an event.** Running the same camp, course or breakfast again? Press **Copy** on the event
+  and the editor opens with everything filled in: tickets and prices, early birds, sessions, the
+  form, feedback questions, certificates and groups.
+- **Pick the new start date** and every other date moves with it — sessions, deadlines and
+  early-bird dates included. Check each step, change what's different this time, and save.
+- Registrations, coupons, attachments, kids check-in and volunteer roles aren't copied.
+
+## 1.46.2
+
+- **See what's new before you update.** When a new version is out, the Licence page lists what it
+  brings, so you can decide whether you want it.
+- **Changed your mind?** Withdraw an update request, and your provider is told not to update the site.
+- **Not now:** hide the "update available" reminder until the next version comes out. Updates that
+  fix a security problem or a serious bug are marked in red and can't be put off.
+- **Notices from your provider**, such as planned maintenance, now show as a banner for site admins
+  and supervisors.
+
+## 1.46.1
+
+- Behind-the-scenes maintenance. Nothing changes for you.
+
+## 1.46.0
+
+- **Volunteer rosters:** set up serving roles (Welcome, Parking, Kids, Sound…) per event or session.
+  Anyone with an account can sign up under My account → Serving, or supervisors can assign people.
+- Reminders by WhatsApp or email the day before a shift.
+- **"Can't make it" swaps:** a volunteer asks for cover, and the first to accept takes the place.
+- Volunteers check in by scanning the event's QR code; kids-room volunteers count as leaders on duty.
+- Roster sheet with phone numbers and check-in times, and hours served per person.
+- Fixed: the free kids check-in ticket was offered on the public event page.
+
+## 1.45.1
+
+- The built-in privacy notice and terms of use are brought up to date for kids check-in, sessions,
+  certificates and campuses. If you published your own privacy notice, review it under Admin →
+  Privacy.
+
+## 1.45.0
+
+- **Kids check-in:** a secure check-in and pickup for children's ministry, run from a staff desk, with
+  no label printers needed.
+- Parents keep their children's details (allergies, medical and custody notes) and authorised adults
+  under My account → Kids.
+- Each check-in gives the family a pickup code by WhatsApp or email; children can only be collected
+  with the code.
+- Rooms with age ranges, capacity and ratios, live room screens, and an offline desk mode.
+
+## 1.44.0
+
+- **Staff for some campuses:** supervisors and staff can be limited to certain campuses (Admin →
+  Users). They then see only those campuses' events, plus events for all campuses, everywhere in the
+  dashboard, reports and the scanner.
+- The scanner says which campus a ticket is for.
+
+## 1.43.0
+
+- **Campuses** for churches with more than one campus (Site settings → Campuses, off by default).
+- Events belong to one campus or to all campuses; the public events page has a campus filter and
+  each campus gets its own page.
+- Reports, dashboards, broadcasts and the daily summary can be filtered by campus.
+- People can choose their home campus on their profile.
+
+## 1.42.1
+
+- Behind-the-scenes improvements to licence checking. Nothing changes for you.
+
+## 1.42.0
+
+- **Request update:** when a new version is out, press Request update on Site settings → Licence and
+  your provider updates the site for you.
+
+## 1.41.3
+
+- The platform is now called **Cross Events**. Nothing else changes, and everyone stays signed in.
+
+## 1.41.2
+
+- Fixed: the Background jobs page showed last-run times two hours ahead.
+
+## 1.41.1
+
+- A site without a licence is now read-only until a licence key is connected.
+- Fixed: a site whose licence was released kept showing it as active.
+
+## 1.41.0
+
+- **Licences:** the site connects to Cross Events with a licence key (Site settings → Licence) and
+  checks in every 15 minutes with its version and health — never anyone's personal information.
+- After a licence's end date there's a grace period with a reminder for site admins.
+- Site admins see when a newer version is available.
+
+## 1.40.0
+
+- **POPIA toolkit, part 3:** a privacy readiness checklist with a score, and links to fix each item.
+- **Retention settings:** choose how long personal information is kept. Inactive accounts are warned
+  and then anonymised after 5 years (on by default).
+- **Breach register:** record security incidents, with draft messages for the people affected and
+  for the Information Regulator.
+
+## 1.39.0
+
+- **POPIA toolkit, part 2:** Admin → Privacy (POPIA).
+- Edit and publish your own privacy notice, with numbered versions, and ask everyone to accept a new
+  version when it changes significantly.
+- A register of the outside services that handle personal information, a consent log, and an access
+  log of who downloaded personal information.
+
+## 1.38.0
+
+- **POPIA toolkit, part 1:** a Privacy page for everyone (My account → Privacy): choose whether to get
+  news by email or WhatsApp, download your data, ask for a correction or delete your account.
+- Bulk messages are either **event updates** (to everyone booked) or **news** (only to people who
+  opted in, with an unsubscribe link). Replying STOP on WhatsApp stops news.
+- Admins handle correction and deletion requests under Admin → Data requests.
+
+## 1.37.4
+
+- Behind-the-scenes improvements to updating the site. Nothing changes for you.
+
+## 1.37.3
+
+- Behind-the-scenes fix. Nothing changes for you.
+
+## 1.37.2
+
+- **Payment status checks:** online payments whose confirmation never arrived from PayFast are found
+  and recorded automatically, with a "Check status" button under Payments → Reconcile.
+- A "Test connection" button for the PayFast settings.
+
+## 1.37.1
+
+- "Pay online" is no longer offered when online payments are off or the amount is under R15; people
+  are told to pay at the event instead.
+
+## 1.37.0
+
+- **PayFast:** a second online payment provider (card, instant EFT and more), set up in Site
+  settings → Payments.
+- When more than one provider is on, people choose how to pay.
+
+## 1.36.0
+
+- **Site settings → Payments:** turn online payment providers on or off and choose their order.
+- Online payments must be at least R15; smaller balances are paid at the door.
+
+## 1.35.1
+
+- **Waitlist per session** on events where people pick sessions.
+- "All sessions" tickets let people choose which sessions they'll come to.
+- At the door, walk-ins can be booked straight into today's session.
+- Several fixes for per-session tickets and stock limits.
+
+## 1.35.0
+
+- **Pick sessions:** a multi-session event can let people choose which sessions to come to — day
+  passes for a conference, or a weekly drop-in class — with a price per session.
+- Each session can have its own capacity, and tickets only scan on their own session.
+
+## 1.34.0
+
+- **Background jobs page** (Site settings → Background jobs): see every scheduled task, when it last
+  ran, and run it now.
+- Scheduled tasks (reminders, summaries, backups) are more reliable and run on South African time.
+- Fixed: at the door, multi-day tickets showed as used up from the second session.
+
+## 1.33.0
+
+- **Multi-day events:** an event can run over several sessions (e.g. every Wednesday for 5 weeks);
+  people register and pay once.
+- Check-in per session, optional reminders before each session, and late joining at a lower price.
+- **Attendance register** with ticks per session and Excel/PDF export.
+- **Completion certificates** with four designs, issued automatically, each with a QR code anyone can
+  check.
+
+## 1.32.0
+
+- Event cards show an "Early bird" ribbon while early-bird pricing is running.
+
+## 1.31.1
+
+- A field for Google Search Console verification (Site settings → Organisation).
+
+## 1.31.0
+
+- The registration funnel recognises visits from Facebook, Instagram, Google and other sites without
+  tagged links, and shows shares and QR code scans separately.
+- Events can appear in Google's event listings with their date, venue and tickets.
+
+## 1.30.1
+
+- All tickets — emailed, WhatsApped and printed — share one clean design, with bigger QR codes.
+
+## 1.30.0
+
+- People can add an optional **donation** when they register, paid together with their tickets.
+- Fixed: event pages with a waitlist could crash.
+
+## 1.29.1
+
+- The Coupon codes page is easier to use, including on phones, and hides codes that are off, expired
+  or used up.
+
+## 1.29.0
+
+- Bundle deals come in four types: an exact set, pick any mix, buy X get Y free, and group discounts.
+
+## 1.28.3
+
+- Fixed: the bundle deals form didn't fit on the screen.
+
+## 1.28.2
+
+- The Bundle deals page has a new layout that works on phones.
+
+## 1.28.1
+
+- Bundle deals work at the door, in manual registration and on the self-service kiosk too.
+
+## 1.28.0
+
+- **Bundle deals:** sell a set of tickets together for one price, e.g. 2 adults + 3 kids for R220.
+  They apply automatically, with no code, and the saving shows on invoices and receipts.
+
+## 1.27.1
+
+- Behind-the-scenes improvements to the demo data. Nothing changes for you.
+
+## 1.27.0
+
+- **Cashups** record where each payment method's money ended up: in the bank, cash on hand, or still
+  pending. Card fees and bank charges can be written off with a reason.
+- Pending money can be marked received later without reopening the event.
+- Every dashboard page has the same "Back to dashboard" link.
+
+## 1.26.1
+
+- Behind-the-scenes improvements to the demo data. Nothing changes for you.
+
+## 1.26.0
+
+- Behind-the-scenes upgrades and security updates.
+- Fixed: the refund reason didn't show at the door.
+
+## 1.25.1
+
+- On phones, the cookie notice and the help button no longer hide each other or the menu.
+
+## 1.25.0
+
+- **Yoco settings** in Site settings: enter and check the secret key, and set up payment
+  notifications with one click.
+
+## 1.24.0
+
+- **Ticket transfers** now need the new holder to accept, by a link sent to them.
+- Updated terms of use and privacy policy, with a full cookie policy and a "Cookie settings" link.
+- Fixed: activating an account didn't sign you in.
+
+## 1.23.0
+
+- **View as user:** admins can see the site exactly as someone else does, to help with problems.
+  It's read-only, limited to 30 minutes and recorded in the audit log.
+
+## 1.22.0
+
+- **Registration funnel report:** see where people drop off between viewing an event and paying, by
+  traffic source and device. Only visitors who allow it are counted.
+
+## 1.21.0
+
+- **Post-event feedback:** send a short survey after an event, with one reminder, and see the results
+  in a Feedback summary report.
+- New form question types: star ratings and multiple choice.
+
+## 1.20.0
+
+- **Sponsor a spot:** people can pay for a place for someone who can't afford it, with an optional
+  goal and progress bar.
+
+## 1.19.0
+
+- **Rooms & groups** for camps: put attendees into rooms, cabins, small groups or buses by drag and
+  drop or automatically, with printable lists.
+- Events can ask each person's gender.
+
+## 1.18.0
+
+- **Ticket transfer:** hand a ticket to someone else before the event; the old QR code stops working.
+
+## 1.17.0
+
+- **Offline ticket scanning:** download an event's tickets to a device and keep scanning without a
+  connection; scans sync when it's back online.
+
+## 1.16.0
+
+- **Waitlists** for sold-out tickets: when a place frees up, the next person is offered it
+  automatically.
+
+## 1.15.0
+
+- **Parental consent** for youth events: parents give consent online, with optional medical and
+  emergency details, before their child can be checked in.
+
+## 1.14.0
+
+- **Named attendees:** when booking for several people, each person can be named and get their own
+  ticket.
+
+## 1.13.0
+
+- **Coupon codes:** percentage, fixed-amount or free codes, with limits on events, dates and uses.
+- Staff prices for tickets.
+- A Discounts report.
+
+## 1.12.0
+
+- Two-factor login is now required for admins and supervisors.
+
+## 1.11.0
+
+- **Two-factor login** for everyone who wants it: a code by email or WhatsApp after the password, and
+  "Trust this device for 30 days".
+
+## 1.10.6
+
+- Security updates.
+
+## 1.10.5
+
+- Events that have started but not finished stay listed on the home and events pages.
+
+## 1.10.4
+
+- Fixed: "Add to calendar" didn't work.
+
+## 1.10.3
+
+- More admin actions are written to the audit log.
+
+## 1.10.2
+
+- Behind-the-scenes fix to error monitoring. Nothing changes for you.
+
+## 1.10.1
+
+- Security fixes for file uploads, and security updates.
+
+## 1.10.0
+
+- **Add to calendar** on event pages and in confirmation emails.
+- Better link previews and search engine listings for events.
+- **Nightly database backups**, which you can download from Site settings → Backups.
+- **Audit log** of refunds, donations, manual registrations, cancellations, event changes and
+  settings changes.
+
+## 1.9.5
+
+- The site copes better with automated traffic probing for pages that don't exist.
+
+## 1.9.4
+
+- Behind-the-scenes server setting. Nothing changes for you.
+
+## 1.9.3
+
+- People registered at the door or by staff get their account activation link straight away.
+- Fixed: the self-service kiosk's "Choose a password" didn't work.
+
+## 1.9.2
+
+- Contact-only events no longer get a daily summary email.
+
+## 1.9.1
+
+- Fixed: the browser tab and home page showed the default name instead of your church's name.
+
+## 1.9.0
+
+- Events have a **location**, with a "Directions" link and a map on the event and contact pages.
+
+## 1.8.0
+
+- **Contact-only events** (e.g. baptism) show a "Contact us" button instead of registration.
+- **Invoices and receipts** as branded PDFs with registration and payment emails, with a "pay now"
+  link and QR code.
+- Fixed: buying more tickets after early bird ended re-priced the tickets already bought.
+
+## 1.7.0
+
+- **Brand colours:** primary, secondary and accent colours across the whole site and emails, a
+  favicon, and a live preview. Colours can be suggested from your logo.
+
+## 1.6.0
+
+- Supervisors can unassign a donation that was applied to a registration.
+- Faster payments and dashboards.
+
+## 1.5.4
+
+- The home page shows "My Dashboard" to people who are signed in.
+
+## 1.5.3
+
+- Fixed: help popups could be taller than a phone screen.
+
+## 1.5.2
+
+- Dashboard tiles and charts fit better on phones.
+
+## 1.5.1
+
+- Fixed: scheduled WhatsApp messages were sent as emails.
+
+## 1.5.0
+
+- **Site redesign:** a new look across the whole site, new dashboards with trends and top events, and
+  a "Need help?" button with a guide on every page.
+- A separate Contact page, and recent sign-ins on Profile & Security.
+
+## 1.4.2
+
+- Fixes to how refunds and donations are counted in reports and cashups.
+
+## 1.4.1
+
+- Reports fit better on phones.
+
+## 1.4.0
+
+- **Reports redesigned:** filters that apply to every report, charts, and styled PDF and Excel
+  exports, by email or WhatsApp too.
+- Cashups show who recorded each payment, with per-person cash counts.
+- A payment link placeholder for messages to attendees.
+
+## 1.3.2
+
+- The self-service kiosk is safer with returning visitors' details, and asks before changing them.
+
+## 1.3.1
+
+- The self-service kiosk can find a returning visitor's account.
+
+## 1.3.0
+
+- **Check-in at the door** by number of people, without scanning each QR code, and a confirmation
+  message to the ticket holder.
+
+## 1.2.0
+
+- "Make payment" goes straight to paying the full balance.
+- Staff can record a payment straight after a manual registration.
+
+## 1.1.0
+
+- A payment history page in My account.
+- Registration status shows as a coloured badge.
+
+## 1.0.1
+
+- Closed and past events are tidied away in My Events.
+
+## 1.0.0
+
+- The first release.

backend/.env.example

@@ -75,6 +75,13 @@ WAITLIST_JOB_ENABLED=true
 # WAITLIST_JOB_INTERVAL_MS=600000
 # Payments: every 15 minutes, look up PayFast checkouts whose notification never arrived
 PAYMENT_STATUS_JOB_ENABLED=true
+# Volunteer rosters: reminders the day before a shift (every 15 minutes)
+VOLUNTEER_JOBS_ENABLED=true
+SERIES_JOBS_ENABLED=true
+WEBHOOKS_JOBS_ENABLED=true
+WEBHOOKS_ENABLED=true
+# Local testing only: lets webhook endpoints be http:// or on a private network
+WEBHOOKS_ALLOW_PRIVATE=false
 # Privacy (POPIA): daily 08:00 reminder to admins of data requests due within a week
 PRIVACY_JOBS_ENABLED=true
 # Privacy (POPIA): nightly 03:30 retention job (Admin → Privacy → Retention). Note: inactive

backend/API_DOCUMENTATION.md

@@ -2,6 +2,14 @@
 
 Full interactive docs (with request/response examples) are available at `GET /docs?token=<admin-jwt>` on the running backend.
 
+> **API v2 (1.51.0 on):** `/api/v2` is described by OpenAPI 3.1. The reference is at `/docs/v2`
+> (admin token), the document at `GET /api/v2/openapi.json` (admin). It is generated from the route
+> declarations, so it is not repeated here. v2 responses are `{ data }` (lists add
+> `meta: { page, limit, total, pages }`, `?page=&limit=` up to 100) and errors
+> `{ error: { code, message, fields? } }`. This file documents v1 (`/api/…`). v1 endpoints that have a v2 replacement send `Deprecation` and
+> `Link: <v2 path>; rel="successor-version"` headers (1.51.3). The frontend calls v2 through the typed
+> `apiV2()` helper (`frontend/src/lib/apiV2.ts`, types regenerated with `npm run api:types`).
+
 All authenticated requests require:
 ```
 Authorization: Bearer <jwt>
@@ -136,6 +144,7 @@ At login, if a WhatsApp code can't be sent, the code falls back to the account's
 | GET | `/api/events/by-alias/:redirectUrl` | public | Get event by URL alias |
 | POST | `/api/events` | supervisor+ | Create event |
 | PUT | `/api/events/:id` | supervisor+ | Update event |
+| POST | `/api/events/:id/copy-from` | supervisor+ | Copying an event: copy `fromEventId`'s allocation sets/groups (not kids rooms) and, for admins, planned costs into this new event (409 once it has registrations or groups) |
 | DELETE | `/api/events/:id` | admin | Delete event |
 | POST | `/api/events/:id/email-attendees` | supervisor+ | Bulk email attendees (`dryRun: true` to preview) |
 | POST | `/api/events/:id/email-attendees/schedule` | supervisor+ | Schedule bulk email |
@@ -170,6 +179,10 @@ At login, if a WhatsApp code can't be sent, the code falls back to the account's
 }
 ```
 
+A copy made with "Copy" on the Events page is an ordinary `POST /api/events` from the event form,
+with `clonedFromId` (the source event, noted in the `event_created` audit entry), followed by the
+options, feedback form, sections and recipients as for a new event, then `POST /api/events/:id/copy-from`.
+
 ---
 
 ## Event Options & Variants
@@ -238,7 +251,7 @@ Accepted file types: `.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`,
 | PUT | `/api/registrations/:id/forms/draft` | optional | Save form draft |
 | POST | `/api/registrations/:id/forms/responses` | optional | Submit form responses |
 | PUT | `/api/registrations/:id/forms/responses` | supervisor+ | Replace form responses |
-| GET | `/api/registrations` | staff+ | All registrations |
+| GET | `/api/registrations?page=&limit=&unpaid=1&userId=` | staff+ | All registrations (a plain array; paged `{ data, total, page, limit, pages }` when `page` or `limit` is given). `unpaid=1`: still owing (pending, confirmed, partially paid); `userId`: one person's |
 | PUT | `/api/registrations/:id` | staff+ | Update registration status |
 | GET | `/api/registrations/event/:eventId` | staff+ | Registrations for an event |
 | POST | `/api/registrations/manual` | supervisor+ | Manual registration (accepts `couponCode`) |
@@ -565,7 +578,7 @@ The data subject's tools, unsubscribe links and the admin data-requests inbox (`
 | GET | `/api/privacy/unsubscribe/:token` | public (signed token) | What the link is for: an account (masked email, news state) or an address |
 | POST | `/api/privacy/unsubscribe/:token` | public (signed token) | `{ channels?: ["email","whatsapp"] }` — turn news off (default both) |
 | POST | `/api/privacy/unsubscribe/:token/one-click` | public (signed token) | RFC 8058 one-click (from the `List-Unsubscribe` header) — email news off. GET redirects to `/unsubscribe` |
-| GET | `/api/privacy/requests?status=open\|closed\|all` | admin | Data requests (not self-service downloads), with `overdue` and, for open deletions, `blockers` (registrations for events that haven't ended) |
+| GET | `/api/privacy/requests?status=open\|closed\|all&search=&page=&limit=` | admin | Data requests (not self-service downloads), 50 a page (`total`, `pages`), with `overdue` and, for open deletions, `blockers` (registrations for events that haven't ended). `search` matches name or email |
 | POST | `/api/privacy/requests/:id/complete` | admin | `{ response? }` (required for corrections; emailed). Deletion: anonymises the account — 409 while it has blockers. Audited as `data_request_completed` (+ `user_anonymised`) |
 | POST | `/api/privacy/requests/:id/reject` | admin | `{ response, cancelled?: bool }` — reject (or mark withdrawn); a deletion reopens the account. Audited as `data_request_rejected` |
 
@@ -638,7 +651,7 @@ Options and variants also accept an optional `staffPrice`, charged automatically
 | GET | `/api/payments/mypayments` | user+ | Own payments |
 | GET | `/api/payments/:id` | user+ | Payment by ID |
 | GET | `/api/payments/registration/:registrationId` | user+ | Payments for a registration |
-| GET | `/api/payments` | supervisor+ | All payments |
+| GET | `/api/payments?page=&limit=&userId=&from=&donations=1` | supervisor+ | Payments, newest first, paged (`limit` up to 200). `userId`: one person's; `from`: created on/after (ISO); `donations=1`: donations and the legs applying them |
 | GET | `/api/payments/event/:eventId` | staff+ | Payments for an event |
 | PUT | `/api/payments/assign-donation` | supervisor+ | Assign a donation payment to a registration |
 | POST | `/api/payments/refund` | supervisor+ | Create refund record |
@@ -844,10 +857,13 @@ The connection to the Cross Events Hub (`src/hub/`, protocol in `docs/hub-protoc
 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
 | GET | `/health` | public | `{ status, version, db, jobs, lastBackupAt }` — 503 when the database is down |
-| GET | `/api/hub/status` | admin | `{ state: active\|grace\|suspended\|revoked\|unlicensed, readOnly, daysLeft, endsAt, graceEndsAt, licence, connected, keyConfigured, hubUrl, lastHeartbeatAt, lastError, version, latestVersion, updateAvailable }` |
+| GET | `/api/hub/status` | admin | `{ state: active\|grace\|suspended\|revoked\|unlicensed, readOnly, daysLeft, endsAt, graceEndsAt, licence, connected, keyConfigured, hubUrl, lastHeartbeatAt, lastError, version, latestVersion, updateAvailable, urgentUpdate, updateSnoozed, releases: [{ version, releasedAt, urgent, notes }], updateRequest, notices }` — `releases` is what's new in each version newer than this one (from the Hub) |
 | POST | `/api/hub/connect` | admin (incl. the `/setup` token) | `{ licenceKey }` — registers with the Hub; stores the install id, encrypted secret and licence token. Hub errors pass through with their `code` (`LICENCE_NOT_FOUND`, `LICENCE_IN_USE`, `LICENCE_REVOKED`, `HUB_UNREACHABLE`, …). Audited as `hub_connected` |
 | POST | `/api/hub/heartbeat` | admin | Check in now; returns the status |
 | POST | `/api/hub/update-request` | admin | Ask the Hub for this site to be updated (protocol §3a); the provider is told, nothing runs on the site. Returns the status with `updateRequest: { requestedAt, version }` until the site runs that version. `409 UP_TO_DATE`; audited as `hub_update_requested` |
+| POST | `/api/hub/update-request/cancel` | admin | Withdraw the update request; the Hub tells the provider. Returns the status. Audited as `hub_update_request_withdrawn` |
+| POST | `/api/hub/update-snooze` | admin | `{ snooze }` — "Not now": `updateSnoozed` is true (no banner) until a newer version than the one put off is out. `400` when there's no update or it's urgent (security/serious fix). `{ snooze: false }` turns reminders back on. Audited as `hub_update_snoozed` / `hub_update_unsnoozed` |
+| GET | `/api/hub/notices` | supervisor | The provider's notices showing now: `[{ id, level: info\|maintenance\|warning, title, message, startsAt, endsAt, updatedAt }]`, from the last heartbeat |
 
 **Read-only mode** (licence suspended, revoked, or past its grace period): `403 { code: "LICENCE_READ_ONLY" }` on `POST /api/events`, event options and variants, `POST /api/registrations` (and `/manual`), `PUT /api/registrations/:id/options`, `POST /api/payments`, `/payments/checkout` (`/send`), `/payments/yoco-checkout` (`/send`), `/payments/pay/:id`, `POST /api/waitlist`, `POST /api/coupons`, `POST /api/bundles/event/:id`. Everything else — scanning, exports, refunds, cancellations, privacy requests, settings — keeps working, and payment webhooks for payments already started are still processed.
 
@@ -922,6 +938,134 @@ Allergies, medical and custody notes are stored encrypted. Staff routes are camp
 | GET | `/api/kids/events/:eventId/offline?deviceId=&sessionId=` | staff+ | Offline snapshot: board plus `families` and `codes` (20 reserved for the device). Access log `kids_offline` |
 | POST | `/api/kids/events/:eventId/sync` | staff+ | `{ deviceId, occasion, checkIns: [{ clientId, familyId, childId, roomId, code, at }], checkOuts: [{ clientId, collectedBy, at }] }` → `{ checkedIn, checkedOut, conflicts }`; idempotent by `clientId`; audited as `kids_offline_sync` |
 
+Since 1.46.0 board rooms also carry `rostered: [{ userId, name, checkedIn }]` (volunteers on a serving
+role linked to the room); checked-in ones are counted in `leaders`.
+
+## Saved filters
+
+Per person, on list pages `registrations`, `users`, `events`, `reports` (staff+; your own only — someone
+else's id answers 404).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/saved-filters?page=` | Mine for the page, default first |
+| POST | `/api/saved-filters` | `{ page, name, params, isDefault? }` — params: strings, numbers, booleans, lists of strings (≤ 4 KB); same name replaces; ≤ 30 per page |
+| PUT | `/api/saved-filters/:id` | `{ name?, isDefault? }` (one default per page) |
+| DELETE | `/api/saved-filters/:id` | Delete |
+
+## Bulk actions on registrations
+
+`POST /api/registrations/bulk` (supervisor+): `{ action, registrationIds: [...] (≤ 500), ...params }` →
+`{ action, done, skipped, failed, results: [{ id, ok, skipped?, message }] }`. Every id is campus-checked.
+
+| action | params | What happens |
+|--------|--------|--------------|
+| `markPaid` | `method`: cash/eft/card/other, `paidAt?` | A payment for what's still owed (as `POST /api/payments`); refused in licence read-only mode |
+| `cancel` | — | As cancelling one registration (coupons released, waitlist offered); no refund |
+| `moveOption` | `fromOptionId`, `toOptionId` (same event) | The lines, tickets and attendees move to the new ticket, repriced; status recalculated; places checked; refused in read-only mode |
+| `allocate` | `setId`, `groupId` | Each named person placed, as `PUT /api/allocations/sets/:id/assignments` |
+| `message` | `channel`: email/whatsapp, `subject` (email), `text` | Per event, as `POST /api/events/:id/email-attendees` / `whatsapp-attendees` with `filter.registrationIds`, kind "update" |
+
+## Dashboard and command palette
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/api/dashboard/today` | staff+ | `{ events: [{ id, title, startsAt, endsAt, sessionLabel, places, checkedIn, kidsIn, volunteers }], money: { today, todayCount, week } \| null, pending: [{ key, label, count, href, tone }] }` — money and pending for supervisors/admins; campus-scoped |
+| GET | `/api/dashboard/search?q=` | staff+ | `{ results: [{ type: event\|payment\|person\|registration, id, title, subtitle, href }] }` — payments by amount for supervisors, people and registrations for admins |
+
+## Event series
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/api/series` | supervisor+ | Every series with `followers`, `eventCount` and its events (campus-scoped: their campuses' events only) |
+| POST | `/api/series` | supervisor+ | Create: `{ name, slug?, description?, picture? }` (slug made from the name). 409 when the slug is taken |
+| PUT | `/api/series/:id` | supervisor+ | Change any of those fields |
+| DELETE | `/api/series/:id` | admin | Delete; events stay without a series, followers dropped |
+| GET | `/api/series/by-slug/:slug` | public | `{ id, name, slug, description, picture, upcoming, past, following }` — public events only |
+| POST / DELETE | `/api/series/:id/follow` | user | Follow / unfollow |
+| GET | `/api/series/:id/compare` | supervisor+ | Year on year: `{ series, events: [{ eventId, title, startDate, registrations, tickets, income, checkedIn, attendanceRate, sessions, change }] }`, oldest first; `change` is % against the event before. Scoped staff: their campuses' events only |
+
+Events take `seriesId` (null = none) on create and update; `GET /api/events?series=<slug>` lists one
+series; `GET /api/events/:id` includes `series` and `nextInSeries`. The `series` job emails
+followers once per event (`Event.seriesAnnouncedAt`) when it is public and hasn't started.
+
+## Outbound webhooks
+
+Admin only. Endpoints receive `POST` JSON `{ id: "evt_…", type, createdAt, data }` with headers
+`X-CrossEvents-Event`, `X-CrossEvents-Delivery` and `X-CrossEvents-Signature: t=<unix seconds>,v1=<hex>`
+where v1 = HMAC-SHA256(secret, `<t>.<raw body>`). Answer 2xx within 10 s; anything else is retried
+(1 min, 5 min, 30 min, 2 h, 12 h). The same `id` can arrive more than once — de-duplicate on it.
+
+| Type | `data` |
+|------|--------|
+| `registration.created` / `.paid` / `.cancelled` | `registration { id, status, totalDue, amountPaid, items[], seasonPassPurchaseId }`, `event`, `person` |
+| `payment.received` / `payment.refunded` | `payment { id, amount, method, provider, isDonation, registrationId }`, `event`, `person` |
+| `ticket.checked_in` | `checkIn { id, scannedAt, people, manual, offline, session }`, `ticket`, `event`, `person` |
+| `user.created` | `person { id, name, email, phone, role, createdAt }` |
+| `event.published` | `event { id, title, description, startDate, endDate, location, price, goLiveAt, url, campus, series }` |
+| `webhook.test` | `{ message }` (Send test) |
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/outbound-webhooks` | Endpoints with last-week counts, and the event types (each with an `example` of its `data`) |
+| POST | `/api/outbound-webhooks` | `{ name, url, events }` → endpoint plus `secret` (only here) |
+| PUT | `/api/outbound-webhooks/:id` | `{ name?, url?, events?, isActive? }` |
+| DELETE | `/api/outbound-webhooks/:id` | Endpoint and its deliveries |
+| POST | `/api/outbound-webhooks/:id/rotate-secret` | `{ secret }` |
+| POST | `/api/outbound-webhooks/:id/test` | `{ status, statusCode, error }` |
+| GET | `/api/outbound-webhooks/:id/deliveries?status=&limit=&before=` | Delivery log, newest first; `before` (a `createdAt`) loads older ones |
+| POST | `/api/outbound-webhooks/deliveries/:id/resend` | Send again now |
+
+## Season passes
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/api/season-passes?seriesId=` | supervisor+ | Passes with events, normal prices, `share` per event, `sold`, `unpaid` |
+| POST | `/api/season-passes` | supervisor+ | `{ seriesId, name, description?, price, saleEndsAt?, isActive?, items: [{ eventId, eventOptionId, variantId? }] }` |
+| PUT | `/api/season-passes/:id` | supervisor+ | Change it; events and price only while unsold (409) |
+| DELETE | `/api/season-passes/:id` | supervisor+ | Only while unsold |
+| POST | `/api/season-passes/:id/buy` | user | `{ quantity }` → `{ purchaseId, total, paid, redirectUrl, message }`; 409 when not on sale or too few places |
+| POST | `/api/season-passes/purchases/:id/checkout` | user (buyer) | A new checkout for what is still owed |
+| GET | `/api/season-passes/mine` | user | My purchases with their registrations |
+
+A purchase creates one `Registration` per event (`seasonPassPurchaseId`), its line priced at the
+event's share. The checkout's metadata is `{ type: 'season_pass', purchaseId }`; the webhook records
+one `Payment` per registration (`seasonPassPurchaseId`; only the first carries `externalId`).
+`PUT /api/registrations/:id/options` and `POST /api/registrations/:id/coupon` answer 409 for pass
+registrations.
+
+## Volunteer rosters
+
+Volunteer rosters (1.46.0, `src/utils/volunteers.js`). A **serving role** belongs to an event, or to
+one session of a multi-session event (`sessionId` required there), with `needed` people and optional
+`startsAt`/`endsAt` (default: the session's or event's times). A **slot** is a person on a role;
+nobody can hold two slots whose shifts overlap (`409 SHIFT_CLASH`). When `Event.volunteerOptionId`
+is set, each volunteer without a ticket gets a free place on it (cancelled when they leave, moved
+with a swap). `volunteerOptionId` and `kidsOptionId` are left out of public event pages
+(`GET /api/events`, `GET /api/events/:id` for non-staff) and refused on public registration. Staff
+routes are campus-scoped.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/api/volunteers/me` | user | `{ slots, cover, events }` — my shifts (upcoming and the last week; `canCheckIn`, `swapId`, `hasTicket`), open cover requests I could take, and public events with roles |
+| GET | `/api/volunteers/events/:eventId` | user | `{ event, sessions, roles, totals }` — each role with `shift`, `needed`, `filled`, `full`, `mine`, `coverNeeded` (no names) |
+| POST | `/api/volunteers/roles/:id/sign-up` | user | `201 { slotId, ticket }`; `409 ROLE_FULL`, `409 SHIFT_CLASH`. Blocked in licence read-only mode |
+| DELETE | `/api/volunteers/slots/:id` | user | Withdraw (not after check-in or once the shift is over); the event's notify recipients are emailed |
+| POST | `/api/volunteers/slots/:id/swap` | user | `{ note? }` → `{ swapId }` — "can't make it"; the event's other volunteers are told |
+| DELETE | `/api/volunteers/swaps/:id` | user | Cancel my cover request |
+| POST | `/api/volunteers/swaps/:id/accept` | user | Take the place over at once → `{ slotId, role, event }`; `409 SWAP_CLOSED` if someone was first. Both volunteers and the event's notify recipients are told |
+| POST | `/api/volunteers/check-in` | user | `{ qr }` (`SERVE-<token>`) → `{ event, checkedIn: [{ role, kidsRoom }], already }` for my shifts on today. `404 BAD_QR`, `404 NOT_ROSTERED`, `400 NOT_TODAY`. A kids-room role starts a `KidsRoomDuty` (`fromRoster`) |
+| GET | `/api/volunteers/manage/events?all=1` | staff+ | Events with roles from the last 30 days on; `all=1` (supervisors) every upcoming event |
+| GET | `/api/volunteers/manage/events/:eventId?log=1` | staff+ | The roster with `volunteers: [{ slotId, name, phone, email, checkedInAt, checkInMethod, swapOpen, hasTicket }]` per role, and `totals: { needed, filled, checkedIn, fillRate }`. `log=1` writes the access log (`volunteer_roster`) |
+| GET | `/api/volunteers/manage/events/:eventId/qr` | staff+ | `{ token, qr }` — the check-in QR value (the page encodes `/serve/check-in?code=<qr>`) |
+| POST | `/api/volunteers/manage/slots/:id/check-in` | staff+ | `{ undo? }` — check in by hand (or undo, which ends rostered kids-room duty). Audited as `volunteer_checked_in_manual` |
+| GET / PUT | `/api/volunteers/manage/events/:eventId/settings` | supervisor+ | `{ optionId }` — the volunteer ticket: a main ticket covering the whole event, `'new'` for a free "Volunteer" ticket, `null` = off (default). Also returns the event's `kidsRooms`. Audited as `volunteer_settings_updated` |
+| POST | `/api/volunteers/manage/events/:eventId/roles` | supervisor+ | `{ name, needed, sessionId?, startsAt?, endsAt?, description?, kidsRoomId? }`. Audited as `volunteer_roles_changed`; blocked in read-only mode |
+| PUT / DELETE | `/api/volunteers/manage/roles/:id` | supervisor+ | Change / delete a role (delete refused once someone checked in; its volunteers are told) |
+| POST | `/api/volunteers/manage/roles/:id/assign` | supervisor+ | `{ userId }` — allowed beyond `needed`; the person is told. Audited as `volunteer_assigned` |
+| DELETE | `/api/volunteers/manage/slots/:id` | supervisor+ | Take someone off (not after check-in); they're told. Audited as `volunteer_removed` |
+| GET | `/api/volunteers/manage/hours?eventId=&from=&to=` | supervisor+ | `[{ userId, name, shifts, hours, events }]` — checked-in shifts × shift length, most first |
+
 ## Webhooks
 
 | Method | Path | Auth | Description |

backend/DEMO_DATA.md

@@ -1,10 +1,19 @@
 # Demo data
 
-`npm run set-demo` replaces everything in the database with a realistic set of demo data,
-for showing the platform to other churches. It stages six upcoming events with
-registrations, payments, tickets and people, and ten completed events from the past year
-with door sales, check-ins, feedback and cashups. That way every dashboard, report,
-check-in and cashup screen has something to show.
+The demo seeds replace everything in the database with a realistic set of demo data, for
+showing the platform to other churches. Pick the one that looks like the church you're
+showing it to:
+
+| Command (repo root) | For | What's in it |
+|---|---|---|
+| `npm run demo:small` | A small church, one congregation | 3 upcoming events (a sold-out breakfast with a waitlist, a family day, free carols), 4 past events with check-ins and cashups. No campuses, kids check-in, rosters, courses or series. |
+| `npm run demo:events` | Events and conferences (the original demo) | 6 upcoming events (coupons, variants, early birds, a youth camp with consent and cabins, bundles, donations) and 10 past events with every kind of cashup and funnel analytics. |
+| `npm run demo:ministry` | One campus with weekly ministry | The Alpha Course running now (sessions, attendance, late joining, certificates), a finished Marriage Course with certificates, a 3-day conference sold by day, **Kids Church** with families, children, rooms and check-ins, **volunteer rosters**, a **Men's Breakfast series** with followers and a **season pass**, plus a family day, women's conference and carols. |
+| `npm run demo:multicampus` | A church with several campuses | **Campuses** Central, North and South (switched on), events per campus and church-wide, home campuses, staff limited to a campus (Anri Botha → North, Daniel Pillay → South), the breakfast series moving between campuses, kids church and rosters at two campuses, and all the events-demo events spread over the campuses. |
+
+`npm run demo:list` prints the same list. Kids church always has a session **today** with
+children checked in right now, so the kids desk and room screens have something live to
+show on any day.
 
 > **This deletes real data.** Run it only against a database you're happy to wipe, such
 > as a dedicated demo deployment. It is not something to run on a live church site.
@@ -14,11 +23,15 @@ check-in and cashup screen has something to show.
 ## Running it
 
 ```bash
-cd backend
-npm run set-demo            # shows the database it will wipe and asks you to type "demo"
-npm run set-demo -- --yes   # no prompt (for scripts)
+npm run demo:ministry             # (repo root) shows the database it will wipe and asks you to type "demo"
+npm run demo:ministry -- --yes    # no prompt (for scripts)
+# or in backend/:
+npm run set-demo -- --profile=ministry --yes   # without --profile it seeds "events"
 ```
 
+The campuses setting is switched on for `multicampus` and off for the others (site settings
+are otherwise kept). **Restart the backend afterwards** so it picks the setting up.
+
 The script uses `DATABASE_URL` from `backend/.env`. To point it at another database
 for one run, set it in the environment first. A value already in the environment wins
 over `.env`:

backend/README.md

@@ -145,21 +145,29 @@ npm run prisma:generate
 
 ### Demo data
 
-`npm run set-demo` wipes the database (keeping site settings and the admin account) and stages six upcoming demo events with registrations, payments and tickets. See [DEMO_DATA.md](DEMO_DATA.md).
+`npm run set-demo -- --profile=<small|events|ministry|multicampus>` wipes the database (keeping site settings and the admin account) and stages demo data for that kind of church; from the repo root it's `npm run demo:<name>` (`npm run demo:list` describes them). See [DEMO_DATA.md](DEMO_DATA.md).
 
 ---
 
 ## Running the Server
 
 ```bash
-# Development (auto-reload)
+# Development (auto-reload; runs the TypeScript in src/ through tsx)
 npm run dev
 
-# Production
+# Production: build once per update, then start (src/index.js runs the build in dist/)
+npm run build
 npm start
+
+# Type-check only
+npm run typecheck
 ```
 
-Visit `/` for the status page. Visit `/docs?token=<admin-jwt>` for full API documentation (admin only).
+Since 1.51.0 the backend is partly TypeScript (`allowJs`: `.js` compiles as it is, `.ts` is checked
+strictly). `src/index.js` is a small launcher: with plain Node it runs `dist/` when `dist/build.json`
+matches this version, otherwise it compiles on the fly with tsx. The server itself is `src/app.js`.
+
+Visit `/` for the status page. Visit `/docs?token=<admin-jwt>` for the v1 API documentation and `/docs/v2` for the v2 (OpenAPI) reference — both admin only.
 
 ---
 
@@ -532,6 +540,7 @@ Setup: Admin → Site Settings → **Yoco**. Paste the secret key (checked with
 ### PM2 (recommended)
 ```bash
 npm install -g pm2
+npm run build
 pm2 start src/index.js --name hope-events-api
 pm2 save && pm2 startup
 ```

backend/jest.config.js

@@ -1,4 +1,8 @@
 module.exports = {
   testEnvironment: 'node',
-  testMatch: ['**/tests/**/*.test.js'],
+  testMatch: ['**/tests/**/*.test.js', '**/tests/**/*.test.ts'],
+  // TypeScript (src/**/*.ts and tests) runs through ts-jest; plain JS is left as it is.
+  transform: { '^.+\\.ts$': ['ts-jest', { tsconfig: 'tsconfig.json' }] },
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  modulePathIgnorePatterns: ['<rootDir>/dist/'],
 };

backend/package.json

@@ -1,11 +1,11 @@
 {
   "name": "event-management-backend",
-  "version": "1.45.0",
+  "version": "1.51.8",
   "description": "Event Management System Backend",
   "main": "src/index.js",
   "scripts": {
     "start": "node src/index.js",
-    "dev": "node --watch src/index.js",
+    "dev": "tsx watch src/index.js",
     "test": "jest",
     "postinstall": "prisma generate",
     "prisma:generate": "prisma generate",
@@ -14,34 +14,49 @@
     "prisma:reset": "prisma migrate reset --force",
     "migrate:env-to-db": "node scripts/migrate-env-to-db.js",
     "migrate:env-to-db:dry": "node scripts/migrate-env-to-db.js --dry-run",
-    "set-demo": "node scripts/set-demo.js"
+    "set-demo": "node scripts/set-demo.js",
+    "build": "tsc -p tsconfig.json && node -e \"require('fs').writeFileSync('dist/build.json', JSON.stringify({ version: require('./package.json').version, builtAt: new Date().toISOString() }))\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "openapi": "tsx scripts/openapi.ts"
   },
   "dependencies": {
+    "@cj-tech-master/excelts": "^10.2.0",
     "@prisma/adapter-pg": "^7.10.1",
     "@prisma/client": "^7.10.1",
     "@sentry/node": "^10.71.0",
     "axios": "^1.11.0",
     "bcryptjs": "^2.4.3",
     "cors": "^2.8.5",
-    "cron-parser": "^4.9.0",
+    "cron-parser": "^5.10.2",
     "dotenv": "^16.3.1",
-    "exceljs": "^4.4.0",
-    "express": "^4.18.2",
+    "express": "^5.3.0",
     "express-rate-limit": "^8.6.2",
     "ics": "^3.12.0",
     "jsonwebtoken": "^9.0.3",
-    "multer": "^2.2.0",
+    "multer": "^2.5.0",
     "node-fetch": "^2.7.0",
-    "nodemailer": "^10.0.16",
+    "nodemailer": "^10.3.0",
     "pdfkit": "^0.17.1",
-    "pg-boss": "^10.4.2",
+    "pg-boss": "^11.1.2",
     "qrcode": "^1.5.4",
     "raw-body": "^3.0.0",
-    "uuid": "^11.1.1"
+    "swagger-ui-dist": "^5.34.0",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "uuid": "^11.1.1",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^20.19.43",
+    "@types/supertest": "^7.2.1",
+    "@types/swagger-ui-dist": "^3.30.6",
     "jest": "^30.4.2",
-    "prisma": "^7.10.1"
+    "prisma": "^7.10.1",
+    "supertest": "^7.3.1",
+    "ts-jest": "^29.4.15"
   },
   "overrides": {
     "uuid": "^11.1.1",
@@ -54,6 +69,11 @@
     "prisma@7.10.1": true,
     "@prisma/engines@7.10.1": true,
     "unrs-resolver@1.12.2": true,
-    "@parcel/watcher": false
+    "@parcel/watcher": false,
+    "@scarf/scarf": false,
+    "esbuild": false
+  },
+  "engines": {
+    "node": ">=22"
   }
 }

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;
+

backend/prisma/migrations/20261028130000_hub_update_choices/migration.sql

@@ -0,0 +1,11 @@
+-- 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 'hub_update_request_withdrawn';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'hub_update_snoozed';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'hub_update_unsnoozed';

backend/prisma/migrations/20261028140000_event_series/migration.sql

@@ -0,0 +1,59 @@
+-- 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 'series_created';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'series_updated';
+ALTER TYPE "AdminAuditAction" ADD VALUE 'series_deleted';
+
+-- AlterTable
+ALTER TABLE "Event" ADD COLUMN     "seriesAnnouncedAt" TIMESTAMP(3),
+ADD COLUMN     "seriesId" TEXT;
+
+-- CreateTable
+CREATE TABLE "EventSeries" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "slug" TEXT NOT NULL,
+    "description" TEXT,
+    "picture" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "EventSeries_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "SeriesFollow" (
+    "id" TEXT NOT NULL,
+    "seriesId" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "SeriesFollow_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "EventSeries_slug_key" ON "EventSeries"("slug");
+
+-- CreateIndex
+CREATE INDEX "SeriesFollow_userId_idx" ON "SeriesFollow"("userId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "SeriesFollow_seriesId_userId_key" ON "SeriesFollow"("seriesId", "userId");
+
+-- CreateIndex
+CREATE INDEX "Event_seriesId_idx" ON "Event"("seriesId");
+
+-- AddForeignKey
+ALTER TABLE "Event" ADD CONSTRAINT "Event_seriesId_fkey" FOREIGN KEY ("seriesId") REFERENCES "EventSeries"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "SeriesFollow" ADD CONSTRAINT "SeriesFollow_seriesId_fkey" FOREIGN KEY ("seriesId") REFERENCES "EventSeries"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "SeriesFollow" ADD CONSTRAINT "SeriesFollow_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

backend/prisma/migrations/20261028150000_season_pass/migration.sql

@@ -0,0 +1,102 @@
+-- AlterEnum
+ALTER TYPE "AdminAuditAction" ADD VALUE 'season_pass_changed';
+
+-- AlterTable
+ALTER TABLE "Payment" ADD COLUMN     "seasonPassPurchaseId" TEXT;
+
+-- AlterTable
+ALTER TABLE "Registration" ADD COLUMN     "seasonPassPurchaseId" TEXT;
+
+-- CreateTable
+CREATE TABLE "SeasonPass" (
+    "id" TEXT NOT NULL,
+    "seriesId" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "description" TEXT,
+    "price" DOUBLE PRECISION NOT NULL,
+    "isActive" BOOLEAN NOT NULL DEFAULT true,
+    "saleEndsAt" TIMESTAMP(3),
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "SeasonPass_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "SeasonPassItem" (
+    "id" TEXT NOT NULL,
+    "passId" TEXT NOT NULL,
+    "eventId" TEXT NOT NULL,
+    "eventOptionId" TEXT NOT NULL,
+    "variantId" TEXT,
+    "order" INTEGER NOT NULL DEFAULT 0,
+
+    CONSTRAINT "SeasonPassItem_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "SeasonPassPurchase" (
+    "id" TEXT NOT NULL,
+    "passId" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "quantity" INTEGER NOT NULL,
+    "total" DOUBLE PRECISION NOT NULL,
+    "status" TEXT NOT NULL DEFAULT 'pending',
+    "checkoutId" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "SeasonPassPurchase_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "SeasonPass_seriesId_idx" ON "SeasonPass"("seriesId");
+
+-- CreateIndex
+CREATE INDEX "SeasonPassItem_eventId_idx" ON "SeasonPassItem"("eventId");
+
+-- CreateIndex
+CREATE INDEX "SeasonPassItem_eventOptionId_idx" ON "SeasonPassItem"("eventOptionId");
+
+-- CreateIndex
+CREATE INDEX "SeasonPassItem_variantId_idx" ON "SeasonPassItem"("variantId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "SeasonPassItem_passId_eventId_key" ON "SeasonPassItem"("passId", "eventId");
+
+-- CreateIndex
+CREATE INDEX "SeasonPassPurchase_passId_idx" ON "SeasonPassPurchase"("passId");
+
+-- CreateIndex
+CREATE INDEX "SeasonPassPurchase_userId_idx" ON "SeasonPassPurchase"("userId");
+
+-- CreateIndex
+CREATE INDEX "SeasonPassPurchase_checkoutId_idx" ON "SeasonPassPurchase"("checkoutId");
+
+-- AddForeignKey
+ALTER TABLE "SeasonPass" ADD CONSTRAINT "SeasonPass_seriesId_fkey" FOREIGN KEY ("seriesId") REFERENCES "EventSeries"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "SeasonPassItem" ADD CONSTRAINT "SeasonPassItem_passId_fkey" FOREIGN KEY ("passId") REFERENCES "SeasonPass"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "SeasonPassItem" ADD CONSTRAINT "SeasonPassItem_eventId_fkey" FOREIGN KEY ("eventId") REFERENCES "Event"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "SeasonPassItem" ADD CONSTRAINT "SeasonPassItem_eventOptionId_fkey" FOREIGN KEY ("eventOptionId") REFERENCES "EventOption"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "SeasonPassItem" ADD CONSTRAINT "SeasonPassItem_variantId_fkey" FOREIGN KEY ("variantId") REFERENCES "OptionVariant"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "SeasonPassPurchase" ADD CONSTRAINT "SeasonPassPurchase_passId_fkey" FOREIGN KEY ("passId") REFERENCES "SeasonPass"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "SeasonPassPurchase" ADD CONSTRAINT "SeasonPassPurchase_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "Registration" ADD CONSTRAINT "Registration_seasonPassPurchaseId_fkey" FOREIGN KEY ("seasonPassPurchaseId") REFERENCES "SeasonPassPurchase"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "Payment" ADD CONSTRAINT "Payment_seasonPassPurchaseId_fkey" FOREIGN KEY ("seasonPassPurchaseId") REFERENCES "SeasonPassPurchase"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+

backend/prisma/migrations/20261028160000_webhooks/migration.sql

@@ -0,0 +1,54 @@
+-- AlterEnum
+ALTER TYPE "AdminAuditAction" ADD VALUE 'webhook_endpoint_changed';
+
+-- CreateTable
+CREATE TABLE "WebhookEndpoint" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "url" TEXT NOT NULL,
+    "secret" TEXT NOT NULL,
+    "events" TEXT[],
+    "isActive" BOOLEAN NOT NULL DEFAULT true,
+    "operatorId" TEXT,
+    "lastSuccessAt" TIMESTAMP(3),
+    "lastFailureAt" TIMESTAMP(3),
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "WebhookEndpoint_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "WebhookDelivery" (
+    "id" TEXT NOT NULL,
+    "endpointId" TEXT NOT NULL,
+    "eventId" TEXT NOT NULL,
+    "type" TEXT NOT NULL,
+    "payload" JSONB NOT NULL,
+    "status" TEXT NOT NULL DEFAULT 'pending',
+    "attempts" INTEGER NOT NULL DEFAULT 0,
+    "nextAttemptAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "lastStatusCode" INTEGER,
+    "lastError" TEXT,
+    "deliveredAt" TIMESTAMP(3),
+    "userId" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "WebhookDelivery_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "WebhookDelivery_status_nextAttemptAt_idx" ON "WebhookDelivery"("status", "nextAttemptAt");
+
+-- CreateIndex
+CREATE INDEX "WebhookDelivery_endpointId_createdAt_idx" ON "WebhookDelivery"("endpointId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "WebhookDelivery_userId_idx" ON "WebhookDelivery"("userId");
+
+-- CreateIndex
+CREATE INDEX "WebhookDelivery_createdAt_idx" ON "WebhookDelivery"("createdAt");
+
+-- AddForeignKey
+ALTER TABLE "WebhookDelivery" ADD CONSTRAINT "WebhookDelivery_endpointId_fkey" FOREIGN KEY ("endpointId") REFERENCES "WebhookEndpoint"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+

backend/prisma/migrations/20261028170000_registrations_bulk/migration.sql

@@ -0,0 +1,3 @@
+-- AlterEnum
+ALTER TYPE "AdminAuditAction" ADD VALUE 'registrations_bulk';
+

backend/prisma/migrations/20261028180000_saved_filters/migration.sql

@@ -0,0 +1,23 @@
+-- CreateTable
+CREATE TABLE "SavedFilter" (
+    "id" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "page" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "params" JSONB NOT NULL,
+    "isDefault" BOOLEAN NOT NULL DEFAULT false,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "SavedFilter_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "SavedFilter_userId_page_idx" ON "SavedFilter"("userId", "page");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "SavedFilter_userId_page_name_key" ON "SavedFilter"("userId", "page", "name");
+
+-- AddForeignKey
+ALTER TABLE "SavedFilter" ADD CONSTRAINT "SavedFilter_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+

backend/prisma/schema.prisma

@@ -158,6 +158,16 @@ model User {
   kidsAlertsRaised    KidsAlert[]
   kidsRoomDuties      KidsRoomDuty[]
 
+  // Volunteer rosters (1.46.0)
+  volunteerSlots      VolunteerSlot[] @relation("VolunteerSlotUser")
+  volunteersAssigned  VolunteerSlot[] @relation("VolunteerSlotAssignedBy")
+  volunteersCheckedIn VolunteerSlot[] @relation("VolunteerSlotCheckedInBy")
+  seriesFollows       SeriesFollow[]
+  seasonPassPurchases SeasonPassPurchase[]
+  savedFilters        SavedFilter[]
+  swapsAsked          VolunteerSwap[] @relation("VolunteerSwapFrom")
+  swapsTaken          VolunteerSwap[] @relation("VolunteerSwapTo")
+
   @@index([homeCampusId])
 }
 
@@ -304,10 +314,117 @@ 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
+
+  // Event series (1.47.1): separate events grouped on one series page (Camp 2025, Camp 2026).
+  // seriesAnnouncedAt: when followers were emailed that this event is out (once, when it goes live).
+  seriesId               String?
+  series                 EventSeries?     @relation(fields: [seriesId], references: [id], onDelete: SetNull)
+  seasonPassItems        SeasonPassItem[]
+  seriesAnnouncedAt      DateTime?
+
   @@index([createdById])
   @@index([closedById])
   @@index([reopenedById])
   @@index([campusId])
+  @@index([seriesId])
+}
+
+/// Separate events grouped together, e.g. every year's camp or the monthly men's breakfast.
+/// Not tied to a campus: a series can have events at several campuses.
+model EventSeries {
+  id          String         @id @default(uuid())
+  name        String
+  slug        String         @unique
+  description String?
+  picture     String?
+  createdAt   DateTime       @default(now())
+  updatedAt   DateTime       @updatedAt
+  events      Event[]
+  followers   SeriesFollow[]
+  passes      SeasonPass[]
+}
+
+/// Someone who wants to hear when a new event in the series is out (sent as news).
+model SeriesFollow {
+  id        String      @id @default(uuid())
+  seriesId  String
+  userId    String
+  createdAt DateTime    @default(now())
+  series    EventSeries @relation(fields: [seriesId], references: [id], onDelete: Cascade)
+  user      User        @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([seriesId, userId])
+  @@index([userId])
+}
+
+/// A season pass (1.47.3): one price for a ticket at each of several events in a series. Buying
+/// it registers the buyer for every event on it in one checkout; the price is split across the
+/// events in proportion to their normal ticket prices (for each event's cashup).
+model SeasonPass {
+  id          String               @id @default(uuid())
+  seriesId    String
+  name        String
+  description String?
+  price       Float
+  isActive    Boolean              @default(true)
+  // Stops selling then (it always stops when the first event on it starts).
+  saleEndsAt  DateTime?
+  createdAt   DateTime             @default(now())
+  updatedAt   DateTime             @updatedAt
+  series      EventSeries          @relation(fields: [seriesId], references: [id], onDelete: Cascade)
+  items       SeasonPassItem[]
+  purchases   SeasonPassPurchase[]
+
+  @@index([seriesId])
+}
+
+/// One event on a pass: which ticket (and variant) the pass gives there.
+model SeasonPassItem {
+  id            String         @id @default(uuid())
+  passId        String
+  eventId       String
+  eventOptionId String
+  variantId     String?
+  order         Int            @default(0)
+  pass          SeasonPass     @relation(fields: [passId], references: [id], onDelete: Cascade)
+  event         Event          @relation(fields: [eventId], references: [id], onDelete: Cascade)
+  eventOption   EventOption    @relation(fields: [eventOptionId], references: [id], onDelete: Cascade)
+  variant       OptionVariant? @relation(fields: [variantId], references: [id], onDelete: Cascade)
+
+  @@unique([passId, eventId])
+  @@index([eventId])
+  @@index([eventOptionId])
+  @@index([variantId])
+}
+
+/// Someone's purchase of a pass: `quantity` passes, one registration per event.
+model SeasonPassPurchase {
+  id            String         @id @default(uuid())
+  passId        String
+  userId        String
+  quantity      Int
+  total         Float
+  // pending | paid | cancelled
+  status        String         @default("pending")
+  // The online checkout started for it (our ProviderCheckout id).
+  checkoutId    String?
+  createdAt     DateTime       @default(now())
+  updatedAt     DateTime       @updatedAt
+  pass          SeasonPass     @relation(fields: [passId], references: [id], onDelete: Restrict)
+  user          User           @relation(fields: [userId], references: [id], onDelete: Restrict)
+  registrations Registration[]
+  payments      Payment[]
+
+  @@index([passId])
+  @@index([userId])
+  @@index([checkoutId])
 }
 
 model EventOption {
@@ -331,6 +448,7 @@ model EventOption {
   couponScopes        CouponOption[]
   waitlistEntries     WaitlistEntry[]
   bundleItems         EventBundleItem[]
+  seasonPassItems     SeasonPassItem[]
 
   @@index([eventId])
 }
@@ -367,6 +485,7 @@ model OptionVariant {
   couponScopes        CouponOption[]
   waitlistEntries     WaitlistEntry[]
   bundleItems         EventBundleItem[]
+  seasonPassItems     SeasonPassItem[]
 
   @@index([eventOptionId])
 }
@@ -397,8 +516,13 @@ model Registration {
   formDrafts          FormDraft[]
   couponRedemptions   CouponRedemption[]
   bundleApplications  RegistrationBundle[]
+  // Season pass (1.47.3): one registration per event on the pass, its line priced at that
+  // event's share of the pass price (never repriced, no coupons, options not editable).
+  seasonPassPurchaseId String?
+  seasonPassPurchase   SeasonPassPurchase? @relation(fields: [seasonPassPurchaseId], references: [id], onDelete: SetNull)
   attendees           Attendee[]
   waitlistEntries     WaitlistEntry[]
+  volunteerSlots      VolunteerSlot[]
 
   @@index([userId])
   @@index([eventId])
@@ -486,6 +610,10 @@ model Payment {
   originalPayment   Payment?          @relation("SplitPayments", fields: [originalPaymentId], references: [id], onDelete: SetNull)
   splitPayments     Payment[]         @relation("SplitPayments")
   providerTransactions ProviderTransaction[]
+  // Season pass: one provider payment is recorded as one Payment per event on the pass (its
+  // share), all linked to the purchase. Only the first carries the provider's externalId.
+  seasonPassPurchaseId String?
+  seasonPassPurchase   SeasonPassPurchase? @relation(fields: [seasonPassPurchaseId], references: [id], onDelete: SetNull)
 
   @@index([userId])
   @@index([recordedById])
@@ -666,6 +794,9 @@ enum AdminAuditAction {
   breach_updated
   hub_connected
   hub_update_requested
+  hub_update_request_withdrawn
+  hub_update_snoozed
+  hub_update_unsnoozed
   campuses_toggled
   campus_created
   campus_updated
@@ -678,6 +809,17 @@ 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
+  series_created
+  series_updated
+  series_deleted
+  season_pass_changed
+  webhook_endpoint_changed
+  registrations_bulk
 }
 
 // Append-only audit trail for admin/supervisor-initiated actions with money or
@@ -1364,6 +1506,7 @@ model AllocationGroup {
   kidsCheckIns KidsCheckIn[]
   kidsAlerts   KidsAlert[]
   kidsDuties   KidsRoomDuty[]
+  servingRoles ServingRole[]
 
   @@index([setId])
   @@index([leaderUserId])
@@ -1639,6 +1782,7 @@ model EventSession {
   reminders   SessionReminderLog[]
   registrationOptions RegistrationOption[]
   waitlistEntries     WaitlistEntry[]
+  servingRoles        ServingRole[]
 
   @@index([eventId, startsAt])
 }
@@ -2017,9 +2161,157 @@ 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])
+}
+
+/// Outbound webhooks (1.48.0): a URL that is sent what happens here (registrations, payments,
+/// check-ins, new accounts, published events), signed with its own secret.
+model WebhookEndpoint {
+  id          String            @id @default(uuid())
+  name        String
+  url         String
+  // HMAC secret, encrypted (utils/encryption.js); shown to the admin once, when made or rotated.
+  secret      String
+  // Event types it gets, e.g. ["registration.paid", "ticket.checked_in"].
+  events      String[]
+  isActive    Boolean           @default(true)
+  // The operator register entry made for it (POPIA), if any.
+  operatorId  String?
+  lastSuccessAt DateTime?
+  lastFailureAt DateTime?
+  createdAt   DateTime          @default(now())
+  updatedAt   DateTime          @updatedAt
+  deliveries  WebhookDelivery[]
+}
+
+/// One message to one endpoint, with its retries. Kept 30 days.
+model WebhookDelivery {
+  id             String          @id @default(uuid())
+  endpointId     String
+  // The event's own id (the same for every endpoint it went to) and type.
+  eventId        String
+  type           String
+  payload        Json
+  // pending | sending | retrying | succeeded | failed
+  status         String          @default("pending")
+  attempts       Int             @default(0)
+  nextAttemptAt  DateTime        @default(now())
+  lastStatusCode Int?
+  lastError      String?
+  deliveredAt    DateTime?
+  // Whose personal information is in it, so it can be removed with their account.
+  userId         String?
+  createdAt      DateTime        @default(now())
+  endpoint       WebhookEndpoint @relation(fields: [endpointId], references: [id], onDelete: Cascade)
+
+  @@index([status, nextAttemptAt])
+  @@index([endpointId, createdAt])
+  @@index([userId])
+  @@index([createdAt])
+}
+
+/// A person's saved filters on a list page (1.49.2): `page` is the list (registrations, users,
+/// events, reports), `params` the filter values. At most one default per person and page.
+model SavedFilter {
+  id        String   @id @default(uuid())
+  userId    String
+  page      String
+  name      String
+  params    Json
+  isDefault Boolean  @default(false)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, page, name])
+  @@index([userId, page])
+}

backend/scripts/openapi.ts

@@ -0,0 +1,22 @@
+/**
+ * Writes the /api/v2 OpenAPI document to frontend/src/lib/api-v2/openapi.json, from which the
+ * frontend's types are generated (`npm run api:types` in the repo root does both). Run it after
+ * adding or changing a v2 route; tests/v2.test.ts fails while the saved copy is out of date.
+ */
+import 'dotenv/config';
+import fs from 'fs';
+import path from 'path';
+import { buildOpenApi } from '../src/v2/openapi';
+import '../src/v2';
+
+export const OPENAPI_FILE = path.join(__dirname, '..', '..', 'frontend', 'src', 'lib', 'api-v2', 'openapi.json');
+
+// The version is left out so a release bump doesn't change the file.
+export const currentDocument = () => JSON.stringify(buildOpenApi({ version: 'v2' }), null, 2) + '\n';
+
+if (require.main === module) {
+  fs.mkdirSync(path.dirname(OPENAPI_FILE), { recursive: true });
+  fs.writeFileSync(OPENAPI_FILE, currentDocument());
+  console.log(`Wrote ${path.relative(process.cwd(), OPENAPI_FILE)}`);
+  process.exit(0);
+}

backend/scripts/set-demo.js

@@ -2,9 +2,19 @@
  * set-demo.js
  *
  * Replaces the database contents with demo data for showing the system to other
- * churches: six upcoming events with registrations, payments, tickets, attendee forms,
- * coupons, a waitlist, camp cabins, sponsorships, costs and funnel analytics, plus ten
- * completed events from the past year with door sales, check-ins, feedback and cashups.
+ * churches. Four profiles, for different kinds of church (see PROFILES below, or
+ * `npm run demo:list`):
+ *
+ *   small        One congregation, the essentials: a few events, payments, check-ins, cashups.
+ *   events       Events and conferences (the original demo, the default): six upcoming events
+ *                with coupons, a waitlist, camp cabins, sponsorships, bundles, costs and funnel
+ *                analytics, and ten completed events with door sales, feedback and cashups.
+ *   ministry     One campus with weekly ministry: a multi-session course (attendance and
+ *                certificates), a "pick your days" conference, kids church with kids check-in,
+ *                volunteer rosters, and a Men's Breakfast series with followers and a season pass.
+ *   multicampus  Three campuses: events per campus and church-wide, home campuses,
+ *                campus-limited staff, a series across campuses, kids check-in and rosters at two
+ *                campuses.
  *
  * Everything is removed first EXCEPT the site settings (AppSetting) and the admin
  * account (DEMO_ADMIN_EMAIL, default joshua@crosscode.co.za). Dates are relative to
@@ -13,10 +23,14 @@
  * No emails or WhatsApp messages are sent. Demo people use @example.com addresses and
  * have no phone numbers, so later reminders can't reach a real person.
  *
- * Usage:
- *   cd backend
- *   npm run set-demo            (asks for confirmation)
- *   npm run set-demo -- --yes   (no prompt)
+ * Campuses are switched on (site setting) for "multicampus" and off for the others; restart the
+ * backend afterwards so it picks the setting up.
+ *
+ * Usage (from the repo root):
+ *   npm run demo:small | demo:events | demo:ministry | demo:multicampus   (asks for confirmation)
+ *   npm run demo:list                                                     (what each one has)
+ * or in backend/:
+ *   npm run set-demo -- --profile=ministry --yes                          (no prompt)
  */
 
 'use strict';
@@ -38,6 +52,8 @@ const prisma = createPrismaClient();
 const ADMIN_EMAIL = (process.env.DEMO_ADMIN_EMAIL || 'joshua@crosscode.co.za').trim().toLowerCase();
 const DEMO_PASSWORD = 'Demo@1234';
 const SKIP_PROMPT = process.argv.includes('--yes') || process.argv.includes('-y');
+const PROFILE_NAME = (process.argv.find(a => a.startsWith('--profile=')) || '--profile=events').split('=')[1].trim().toLowerCase();
+const LIST_ONLY = process.argv.includes('--list');
 
 // Not truncated: migrations, site settings, users (all but the admin are deleted
 // separately) and the admin's own account-security rows.
@@ -161,13 +177,16 @@ const add = (model, row) => {
 };
 
 const INSERT_ORDER = [
-  'user', 'event', 'eventOption', 'optionVariant', 'earlyBirdTier', 'section', 'sectionOption',
+  'campus', 'user', 'eventSeries', 'event', 'eventSession', 'eventOption', 'optionVariant', 'earlyBirdTier', 'section', 'sectionOption',
   'eventForm', 'eventFormField', 'coupon', 'couponEvent', 'eventBundle', 'eventBundleItem',
+  'seasonPass', 'seasonPassItem', 'seasonPassPurchase',
   'registration', 'registrationOption', 'registrationOptionTranche', 'attendee', 'payment', 'ticket',
   'ticketUsage', 'couponRedemption', 'registrationBundle',
   'formResponse', 'formAnswer', 'consentRequest', 'waitlistEntry', 'allocationSet',
   'allocationGroup', 'allocationAssignment', 'eventCost', 'feedbackForm', 'feedbackField',
   'feedbackInvite', 'feedbackResponse', 'feedbackAnswer', 'analyticsEvent', 'analyticsDaily',
+  'certificate', 'seriesFollow', 'family', 'familyMember', 'child', 'authorisedAdult',
+  'kidsPickupCode', 'kidsCheckIn', 'kidsRoomDuty', 'servingRole', 'volunteerSlot', 'volunteerSwap',
 ];
 
 // Extra facts about demo people that aren't columns (kept out of the inserted rows).
@@ -314,6 +333,8 @@ function addRegistration(event, user, lines, { createdAt, pay = 'full', method =
       quantity: l.quantity,
       priceSnapshot: price,
       appliedTierId: tier ? tier.id : null,
+      // "Pick sessions" events: a per-session line.
+      sessionId: l.sessionId || null,
     });
     add('registrationOptionTranche', {
       id: uuidv4(),
@@ -823,8 +844,11 @@ const IMPROVEMENTS = [
  * donations { card, cash, amounts }, showRate, feedback (what people enjoyed), cashup.
  */
 function buildPastEvent(people, spec) {
+  // Each profile has its own selection of past events (`always`: built by a profile's extras).
+  if (!spec.always && profile.past && !profile.past.includes(spec.title)) return null;
   const { start } = spec;
   const event = addEvent({
+    ...(spec.seriesId ? { seriesId: spec.seriesId, seriesAnnouncedAt: start } : {}),
     title: spec.title,
     description: spec.description,
     startDate: start,
@@ -1189,6 +1213,524 @@ async function closePastEvents() {
   return results;
 }
 
+// ─── Profiles ────────────────────────────────────────────────────────────────
+
+const UPCOMING = {
+  mensBreakfast: buildMensBreakfast,
+  familyFunDay: buildFamilyFunDay,
+  womensConference: buildWomensConference,
+  youthCamp: buildYouthCamp,
+  carols: buildCarols,
+  marriageWeekend: buildMarriageWeekend,
+};
+
+/**
+ * upcoming: which of the six upcoming events (UPCOMING); past: titles of past events to build
+ * (null = all ten); extras: the newer features (series, courses, conference, kids, volunteers);
+ * campuses: three campuses, switched on.
+ */
+const PROFILES = {
+  small: {
+    title: 'Small church — one congregation, the essentials',
+    about: [
+      'Three upcoming events: a breakfast (sold out, with a waitlist), a family fun day and free carols.',
+      'Four past events with check-ins and cashups (one left open to cash up live).',
+      'No campuses, kids check-in, volunteer rosters, courses or series.',
+    ],
+    campuses: false,
+    upcoming: ['mensBreakfast', 'familyFunDay', 'carols'],
+    past: ['Church Family Picnic', 'Christmas Eve Candlelight Service', 'Easter Sunrise Service & Breakfast', 'Worship Night'],
+    extras: [],
+  },
+  events: {
+    title: 'Events & conferences — the full events demo (default)',
+    about: [
+      'Six upcoming events: breakfast with a waitlist, family day, women\'s conference (variants, early birds, coupons),',
+      'youth camp (parental consent, cabins, medical forms), free carols with donations, marriage weekend (bundles).',
+      'Ten past events with door sales, refunds, feedback and every kind of cashup; funnel analytics.',
+      'One campus; no kids check-in, rosters, courses or series.',
+    ],
+    campuses: false,
+    upcoming: Object.keys(UPCOMING),
+    past: null,
+    extras: [],
+  },
+  ministry: {
+    title: 'Weekly ministry — one campus, courses, kids church and volunteers',
+    about: [
+      'Alpha Course running now (7 weekly sessions, attendance per session, late joining, certificates) and a finished',
+      'Marriage Course with certificates issued; a 3-day leadership conference sold by day ("pick sessions").',
+      'Kids Church every Sunday with kids check-in: families, children (some allergies), rooms with ratios, past check-ins.',
+      'Volunteer rosters for kids church and the family day (sign-ups, QR check-ins, an open cover request).',
+      'A Men\'s Breakfast series (two past, three coming) with followers and a season pass; family day, women\'s conference, carols.',
+    ],
+    campuses: false,
+    upcoming: ['familyFunDay', 'womensConference', 'carols'],
+    past: ['Church Family Picnic', 'Christmas Eve Candlelight Service', 'Kids Holiday Club', 'Youth Winter Camp', 'Worship Night'],
+    extras: ['series', 'courses', 'conference', 'kids', 'volunteers'],
+  },
+  multicampus: {
+    title: 'Multi-campus church — three campuses',
+    about: [
+      'Campuses Central, North and South (switched on), events per campus and church-wide, home campuses for most people.',
+      'Staff limited to a campus: Anri Botha (North) and Daniel Pillay (South).',
+      'The Men\'s Breakfast series moves between the campuses, with followers and a season pass.',
+      'Kids church with kids check-in and volunteer rosters at Central and North.',
+      'All six upcoming and ten past events of the events demo, spread over the campuses.',
+    ],
+    campuses: true,
+    upcoming: ['familyFunDay', 'womensConference', 'youthCamp', 'carols', 'marriageWeekend'],
+    past: null,
+    extras: ['series', 'kids', 'volunteers'],
+  },
+};
+
+let profile = PROFILES[PROFILE_NAME];
+
+const hex = (bytes = 16) => crypto.randomBytes(bytes).toString('hex');
+let campuses = [];
+
+// ─── Campuses (multicampus) ──────────────────────────────────────────────────
+
+function buildCampuses() {
+  const campus = (name, slug, address, colour, defaultLocation, order) => add('campus', {
+    id: uuidv4(), name, slug, address, contactName: 'Lerato Khumalo', contactEmail: `${slug}@example.com`,
+    colour, defaultLocation, order, createdAt: addTime(NOW, -300 * DAY), updatedAt: NOW,
+  });
+  campuses = [
+    campus('Central', 'central', '12 Church Street, Hatfield, Pretoria', '#2563eb', 'Main auditorium', 0),
+    campus('North', 'north', '45 Zambezi Drive, Montana', '#16a34a', 'North campus hall', 1),
+    campus('South', 'south', '8 Lenchen Avenue, Centurion', '#ea580c', 'South campus hall', 2),
+  ];
+  for (const u of rows.user) if (u.role === 'user' && chance(0.85)) u.homeCampusId = pick(campuses).id;
+}
+
+/** Spreads the events over the campuses; the big ones stay church-wide. */
+function assignCampuses() {
+  const byTitle = {
+    'Family Fun Day': 1, 'Carols by Candlelight': 2, 'Youth Winter Camp': null, 'Christmas Eve Candlelight Service': 0,
+    'Rooted Women’s Conference': null, 'Ignite Summer Camp': null, 'Marriage Enrichment Weekend': null,
+  };
+  let i = 0;
+  for (const event of rows.event) {
+    if (event.campusId !== undefined && event.campusId !== null) continue; // set by its builder
+    if (event.seriesId || event.kidsCheckIn) continue;
+    const idx = event.title in byTitle ? byTitle[event.title] : (i++ % campuses.length);
+    event.campusId = idx === null ? null : campuses[idx].id;
+    if (idx !== null && event.location === 'Church hall') event.location = campuses[idx].defaultLocation;
+  }
+}
+
+/** Staff limited to one campus (a many-to-many, so it's set after the rows are in). */
+async function scopeStaff(tx) {
+  const byName = (first) => staffTeam.find(s => s.name.startsWith(first));
+  for (const [first, campusIdx] of [['Anri', 1], ['Daniel', 2]]) {
+    await tx.user.update({ where: { id: byName(first).id }, data: { scopedCampuses: { connect: [{ id: campuses[campusIdx].id }] } } });
+  }
+}
+
+// ─── Event series and a season pass ──────────────────────────────────────────
+
+function buildBreakfast(people, { start, title, sold }) {
+  const event = addEvent({
+    title,
+    description: 'A full breakfast, a guest speaker and an honest conversation about faith, work and family. Bring a friend.',
+    startDate: start,
+    endDate: addTime(start, 2.5 * HOUR),
+    registrationDeadline: addTime(start, -2 * DAY),
+    price: 150,
+    picture: IMG('photo-1414235077428-338989a2e8c0'),
+    location: 'Church hall',
+    contactName: 'Sipho Dlamini',
+  });
+  const ticket = addOption(event, { name: 'Breakfast ticket', price: 150, stockLimit: 60 });
+  addCost(event, 'Breakfast catering', 'per_item', 85, ticket);
+  for (const user of shuffle(people.men).slice(0, sold)) {
+    addRegistration(event, user, [line(ticket, 1)], { createdAt: pastDate(20, 1), ...payPlan({ card: 0.7, eft: 0.1, none: 0.2 }) });
+  }
+  return { event, ticket };
+}
+
+/**
+ * The Men's Breakfast as a series: two past breakfasts (cashed up), this month's (sold out) and two
+ * more, 18 followers, and a season pass for the next two with six bought. On the multi-campus demo
+ * each breakfast is at a different campus.
+ */
+function buildSeries(people) {
+  const series = add('eventSeries', {
+    id: uuidv4(), name: "Men's Breakfast", slug: 'mens-breakfast',
+    description: 'Once a month on a Saturday morning: a full breakfast, a guest speaker and an honest conversation about faith, work and family. Follow the series to hear when the next one is out.',
+    picture: IMG('photo-1414235077428-338989a2e8c0'), createdAt: addTime(NOW, -200 * DAY), updatedAt: NOW,
+  });
+  const campusAt = (i) => (profile.campuses ? campuses[i % campuses.length] : null);
+  const pastSpec = (title, daysAgo, speaker) => ({
+    always: true, seriesId: series.id, title, description: `Breakfast with ${speaker}.`,
+    start: lastWeekday(daysAgo, 6, 7, 30), hours: 2.5, picture: 'photo-1414235077428-338989a2e8c0', location: 'Church hall', pool: 'men',
+    options: [{ name: 'Breakfast ticket', price: 150 }],
+    costs: o => [['Breakfast catering', 'per_item', 85, o[0]]],
+    online: int(34, 42), onlinePay: { card: 80, eft: 15, none: 5 }, door: int(3, 8), doorPay: { cash: 70, card: 30 },
+    lines: o => [line(o[0], chance(0.2) ? 2 : 1)],
+    showRate: 0.9,
+    cashup: { close: 'quick', daysAfter: 3, notes: 'Quick closed — card and cash banked.' },
+  });
+  const past = [
+    buildPastEvent(people, pastSpec("Men's Breakfast: Fathers & Sons", 63, 'Pastor Ernest Molefe')),
+    buildPastEvent(people, pastSpec("Men's Breakfast: Faith at Work", 35, 'Thabo Nkosi')),
+  ];
+  const current = buildMensBreakfast(people);
+  const next = buildBreakfast(people, { start: nextWeekday(36, 6, 7, 30), title: "Men's Breakfast: Leading at Home", sold: 22 });
+  const later = buildBreakfast(people, { start: nextWeekday(64, 6, 7, 30), title: "Men's Breakfast: Money & Generosity", sold: 9 });
+  [...past, current, next.event, later.event].forEach((event, i) => {
+    event.seriesId = series.id;
+    // Followers were told when each came out (so the series job doesn't email demo people).
+    event.seriesAnnouncedAt = event.goLiveAt < NOW ? event.goLiveAt : NOW;
+    const campus = campusAt(i);
+    if (campus) { event.campusId = campus.id; event.location = campus.defaultLocation; }
+  });
+  for (const user of shuffle(people.men).slice(0, 18)) add('seriesFollow', { id: uuidv4(), seriesId: series.id, userId: user.id, createdAt: pastDate(150, 3) });
+
+  // Season pass: the next two breakfasts for R260 (R300 separately), R130 per event.
+  const pass = add('seasonPass', {
+    id: uuidv4(), seriesId: series.id, name: 'Next two breakfasts', description: 'Both of the next breakfasts for one price.',
+    price: 260, isActive: true, saleEndsAt: null, createdAt: addTime(NOW, -20 * DAY), updatedAt: NOW,
+  });
+  [next, later].forEach((b, order) => add('seasonPassItem', { id: uuidv4(), passId: pass.id, eventId: b.event.id, eventOptionId: b.ticket.id, variantId: null, order }));
+  for (const user of shuffle(people.men).slice(0, 6)) {
+    const at = pastDate(15, 1);
+    const purchase = add('seasonPassPurchase', { id: uuidv4(), passId: pass.id, userId: user.id, quantity: 1, total: 260, status: 'paid', checkoutId: null, createdAt: at, updatedAt: at });
+    [next, later].forEach((b, i) => {
+      const reg = add('registration', { id: uuidv4(), userId: user.id, eventId: b.event.id, status: 'paid', discountTotal: 0, bundleDiscount: 0, ticketDelivery: 'payer', analyticsSessionId: null, seasonPassPurchaseId: purchase.id, createdAt: at });
+      const ro = add('registrationOption', { id: uuidv4(), registrationId: reg.id, eventOptionId: b.ticket.id, variantId: null, quantity: 1, priceSnapshot: 130, appliedTierId: null, sessionId: null });
+      add('registrationOptionTranche', { id: uuidv4(), registrationOptionId: ro.id, quantity: 1, priceSnapshot: 130, appliedTierId: null, createdAt: at });
+      add('payment', {
+        id: uuidv4(), amount: 130, method: 'card', userId: user.id, recordedById: null, registrationId: reg.id, eventId: b.event.id,
+        status: 'completed', externalId: i === 0 ? `demo_${uuidv4().replace(/-/g, '')}` : null, seasonPassPurchaseId: purchase.id, createdAt: after(at, 2, 10),
+      });
+      add('ticket', { id: uuidv4(), qrCode: uuidv4(), registrationOptionId: ro.id, userId: user.id, eventId: b.event.id, quantity: 1, emailSent: true, createdAt: at });
+    });
+  }
+  return [current, next.event, later.event];
+}
+
+// ─── Courses and a pick-your-days conference (ministry) ──────────────────────
+
+function addSessions(event, first, count, { everyDays = 7, minutes = 120, labels = [], capacity = null } = {}) {
+  return Array.from({ length: count }, (_, k) => {
+    const startsAt = addTime(first, k * everyDays * DAY);
+    return add('eventSession', {
+      id: uuidv4(), eventId: event.id, label: labels[k] || null, startsAt, endsAt: addTime(startsAt, minutes * MINUTE),
+      order: k, capacity, location: null, createdAt: event.createdAt, updatedAt: NOW,
+    });
+  });
+}
+
+/** Check-ins per session that has ended, for the event's tickets. */
+function attendSessions(event, sessions, showRate) {
+  const attended = new Map();
+  for (const s of sessions.filter(x => x.endsAt < NOW)) {
+    for (const t of rows.ticket.filter(x => x.eventId === event.id)) {
+      if (!chance(showRate)) continue;
+      add('ticketUsage', { id: uuidv4(), ticketId: t.id, scannedById: pick(staffTeam).id, quantityRedeemed: t.quantity, sessionId: s.id, scannedAt: within(addTime(s.startsAt, -20 * MINUTE), addTime(s.startsAt, 15 * MINUTE)) });
+      attended.set(t.id, (attended.get(t.id) || 0) + 1);
+    }
+  }
+  return attended;
+}
+
+const CERTIFICATE = (min) => ({
+  template: 'classic', title: 'Certificate of Completion', signatureImage: '', sendOnIssue: false,
+  body: 'This certifies that {name} has completed {event}, attending {sessionsAttended} of {totalSessions} sessions.',
+  signatureName: 'Pastor Ernest Molefe', signatureRole: 'Senior Pastor', rule: { type: 'count', value: min },
+});
+
+function buildCourses(people) {
+  // Alpha: seven Wednesdays, three already held; late joining until week 4 at a pro-rata price.
+  const first = lastWeekday(15, 3, 18, 30);
+  const alpha = addEvent({
+    title: 'Alpha Course',
+    description: 'Seven Wednesday evenings exploring the big questions of life and faith — each with dinner, a short talk and honest conversation in small groups. Everyone is welcome; no question is off limits.',
+    startDate: first, endDate: addTime(first, (6 * 7) * DAY + 2 * HOUR), price: 250,
+    picture: IMG('photo-1529070538774-1843cb3265df'), location: 'Church hall',
+    scheduleType: 'sessions', attendanceMode: 'whole', lateJoinEnabled: true, latePricing: 'prorata', checkInWindow: 'whole_day',
+    certificatesEnabled: true, certificateConfig: CERTIFICATE(5),
+    goLiveAt: addTime(first, -35 * DAY), createdAt: addTime(first, -40 * DAY),
+  });
+  const alphaSessions = addSessions(alpha, first, 7, { labels: ['Is there more to life than this?', 'Who is Jesus?', 'Why did Jesus die?', 'How can I have faith?', 'Why and how do I pray?', 'How can I resist evil?', 'What about the church?'] });
+  alpha.lateJoinUntilSessionId = alphaSessions[3].id;
+  const alphaTicket = addOption(alpha, { name: 'Course (dinner included)', price: 250, stockLimit: 40 });
+  for (const user of shuffle(people.everyone).slice(0, 30)) {
+    addRegistration(alpha, user, [line(alphaTicket, 1)], { createdAt: daytimeBetween(addTime(first, -30 * DAY), addTime(first, -DAY)), ...payPlan({ card: 0.7, eft: 0.2, none: 0.1 }) });
+  }
+  attendSessions(alpha, alphaSessions, 0.85);
+
+  // Marriage Course: finished six weeks ago; certificates issued to couples who came to 5 of 6.
+  const mFirst = lastWeekday(80, 4, 19);
+  const marriage = addEvent({
+    title: 'The Marriage Course',
+    description: 'Six Thursday evenings for couples: a candle-lit dinner for two, a short talk and time to talk together — no group sharing.',
+    startDate: mFirst, endDate: addTime(mFirst, 35 * DAY + 2 * HOUR), price: 500,
+    picture: IMG('photo-1529634806980-85c3dd6d34ac'), location: 'Church hall',
+    scheduleType: 'sessions', attendanceMode: 'whole', checkInWindow: 'whole_day',
+    certificatesEnabled: true, certificateConfig: CERTIFICATE(5),
+    goLiveAt: addTime(mFirst, -40 * DAY), createdAt: addTime(mFirst, -45 * DAY),
+  });
+  const mSessions = addSessions(marriage, mFirst, 6, { labels: ['Building strong foundations', 'The art of communication', 'Resolving conflict', 'The power of forgiveness', 'Parents and in-laws', 'Love in action'] });
+  const couple = addOption(marriage, { name: 'Couple', price: 500, stockLimit: 16 });
+  for (const user of shuffle(people.everyone).slice(0, 14)) {
+    addRegistration(marriage, user, [line(couple, 1)], { createdAt: daytimeBetween(addTime(mFirst, -35 * DAY), addTime(mFirst, -2 * DAY)), payBy: mFirst, ...payPlan({ card: 0.75, eft: 0.25 }) });
+  }
+  const attended = attendSessions(marriage, mSessions, 0.88);
+  const issuedAt = addTime(mSessions[5].endsAt, DAY);
+  for (const t of rows.ticket.filter(x => x.eventId === marriage.id)) {
+    const n = attended.get(t.id) || 0;
+    if (n < 5) continue;
+    const owner = rows.user.find(u => u.id === t.userId);
+    add('certificate', { id: uuidv4(), eventId: marriage.id, ticketId: t.id, userId: owner.id, name: owner.name, code: hex(4).toUpperCase(), sessionsAttended: n, totalSessions: 6, manual: false, issuedAt, emailedAt: issuedAt });
+  }
+  return [alpha];
+}
+
+function buildLeadershipConference(people) {
+  const day1 = nextWeekday(40, 4, 8, 30);
+  const event = addEvent({
+    title: 'Lead Well Leadership Conference',
+    description: 'Three days for everyone who leads — small groups, ministries, teams at work. Come to all three, or pick the days you can make.',
+    startDate: day1, endDate: addTime(day1, 2 * DAY + 8 * HOUR), price: 650,
+    picture: IMG('photo-1540575467063-178a50c2df87'), location: 'Main auditorium',
+    scheduleType: 'sessions', attendanceMode: 'pick', checkInWindow: 'whole_day',
+  });
+  const days = addSessions(event, day1, 3, { everyDays: 1, minutes: 8 * 60, labels: ['Day 1 — Vision', 'Day 2 — Teams', 'Day 3 — Practice'], capacity: 150 });
+  const full = addOption(event, { name: 'Full conference pass', price: 650, sessionMode: 'all' });
+  addTier(full, { deadline: addTime(day1, -14 * DAY), price: 550, stockLimit: 40 });
+  const dayPass = addOption(event, { name: 'Day pass', price: 280, sessionMode: 'pick' });
+  const buyers = shuffle(people.everyone);
+  for (const user of buyers.splice(0, 34)) {
+    addRegistration(event, user, [line(full, chance(0.2) ? 2 : 1)], { createdAt: pastDate(30, 1), ...payPlan({ card: 0.8, eft: 0.12, none: 0.08 }) });
+  }
+  for (const user of buyers.splice(0, 26)) {
+    const picked = shuffle(days).slice(0, chance(0.4) ? 2 : 1);
+    addRegistration(event, user, picked.map(s => line(dayPass, 1, { sessionId: s.id })), { createdAt: pastDate(25, 1), ...payPlan({ card: 0.8, none: 0.2 }) });
+  }
+  return [event];
+}
+
+// ─── Kids church with kids check-in ──────────────────────────────────────────
+
+const ROOMS = [['Nursery', 0, 2, 3, 12], ['Little Ones', 3, 5, 6, 24], ['Explorers', 6, 9, 8, 30], ['Pre-teens', 10, 12, 10, 24]];
+const inFamily = new Set();
+const kidsChurches = [];
+
+function ageAt(dob, at) {
+  let age = at.getFullYear() - dob.getFullYear();
+  if (at.getMonth() < dob.getMonth() || (at.getMonth() === dob.getMonth() && at.getDate() < dob.getDate())) age--;
+  return Math.max(0, age);
+}
+
+/** A pickup code that's free on this occasion (4 characters, no look-alikes). */
+function kidsCode(taken) {
+  const { CODE_ALPHABET, CODE_LENGTH } = require('../src/utils/kids');
+  for (;;) {
+    let c = '';
+    for (let i = 0; i < CODE_LENGTH; i++) c += CODE_ALPHABET[int(0, CODE_ALPHABET.length - 1)];
+    if (!taken.has(c)) { taken.add(c); return c; }
+  }
+}
+
+/**
+ * Sunday kids church: a hidden event with a session every Sunday (four held, eight to come), the
+ * kids ticket and rooms, 16 families with their children and authorised adults, and check-ins
+ * and check-outs (with pickup codes, tickets and room duty) for the Sundays already held.
+ */
+function buildKidsChurch(people, campus = null) {
+  const { encrypt } = require('../src/utils/encryption');
+  const first = lastWeekday(28, 0, 9, 0);
+  const event = addEvent({
+    title: campus ? `Kids Church — ${campus.name}` : 'Kids Church',
+    description: 'Sunday kids church during the 09:00 service, for babies to 12-year-olds. Check in at the kids desk: each family gets a pickup code, and only someone with the code can collect.',
+    startDate: first, endDate: addTime(first, 77 * DAY + 90 * MINUTE), price: 0, isHidden: true,
+    scheduleType: 'sessions', attendanceMode: 'whole', checkInWindow: 'whole_day', kidsCheckIn: true,
+    location: campus ? `${campus.name} kids wing` : 'Kids wing', campusId: campus ? campus.id : null,
+    goLiveAt: addTime(first, -30 * DAY), createdAt: addTime(first, -32 * DAY),
+  });
+  const sessions = addSessions(event, first, 12, { minutes: 90 });
+  // A session today, so the desk and room screens have children in right now whatever day the
+  // demo is shown (on a Sunday it's that Sunday's session).
+  let live = sessions.find(s => s.startsAt.toDateString() === NOW.toDateString() && s.endsAt > NOW);
+  if (!live) {
+    const startsAt = new Date(NOW); startsAt.setMinutes(0, 0, 0); startsAt.setHours(Math.max(8, startsAt.getHours() - 1));
+    live = add('eventSession', { id: uuidv4(), eventId: event.id, label: 'Midweek Kids Club', startsAt, endsAt: addTime(startsAt, 3 * HOUR), order: 0, capacity: null, location: null, createdAt: event.createdAt, updatedAt: NOW });
+    sessions.push(live);
+    sessions.sort((a, b) => a.startsAt - b.startsAt).forEach((s, order) => { s.order = order; });
+  }
+  const option = addOption(event, { name: 'Kids check-in', price: 0 });
+  event.kidsOptionId = option.id;
+  const set = add('allocationSet', { id: uuidv4(), eventId: event.id, name: 'Kids rooms', showOnTicket: false, order: 0 });
+  event.kidsRoomSetId = set.id;
+  const rooms = ROOMS.map(([name, minAge, maxAge, ratio, capacity], order) => add('allocationGroup', { id: uuidv4(), setId: set.id, name, minAge, maxAge, ratio, capacity, order, gender: null, leaderUserId: null }));
+  const roomFor = age => rooms.find(r => age >= r.minAge && age <= r.maxAge) || rooms[rooms.length - 1];
+
+  const parents = shuffle(people.everyone).filter(u => !inFamily.has(u.id)).slice(0, 16);
+  const families = parents.map(parent => {
+    inFamily.add(parent.id);
+    const { last } = userMeta.get(parent.id);
+    const createdAt = pastDate(200, 40);
+    const family = add('family', { id: uuidv4(), name: `The ${last} family`, qrToken: hex(), createdAt, updatedAt: NOW });
+    add('familyMember', { id: uuidv4(), familyId: family.id, userId: parent.id, createdAt });
+    if (chance(0.5)) {
+      add('authorisedAdult', { id: uuidv4(), familyId: family.id, name: `${pick(chance(0.5) ? FEMALE_FIRST : MALE_FIRST)} ${last}`, phone: null, relationship: pick(['Grandmother', 'Grandfather', 'Aunt', 'Uncle']), createdAt });
+    }
+    const children = Array.from({ length: int(1, 3) }, () => {
+      const girl = chance(0.5);
+      const dob = new Date(NOW);
+      dob.setFullYear(dob.getFullYear() - int(1, 12), int(0, 11), int(1, 28));
+      dob.setHours(0, 0, 0, 0);
+      return add('child', {
+        id: uuidv4(), familyId: family.id, firstName: pick(girl ? GIRL_FIRST : BOY_FIRST), lastName: last, dateOfBirth: dob, gender: girl ? 'female' : 'male',
+        allergies: chance(0.15) ? encrypt(pick(['Peanuts', 'Tree nuts', 'Dairy', 'Eggs', 'Bee stings'])) : null,
+        medicalNotes: chance(0.06) ? encrypt('Asthma — inhaler in the nappy bag') : null,
+        custodyNotes: chance(0.04) ? encrypt('Only the mother or grandmother may collect') : null,
+        lastCheckInAt: null, createdAt, updatedAt: NOW,
+      });
+    });
+    return { parent, family, children };
+  });
+
+  const held = sessions.filter(s => s.endsAt < NOW);
+  const codes = new Map([...held, live].map(s => [s.id, new Set()]));
+  let liveFamilies = 0;
+  for (const f of families) {
+    const attending = held.filter(() => chance(0.75));
+    // About half the families are in right now (checked in, not yet collected).
+    const inNow = live.startsAt <= NOW && liveFamilies < 8 && chance(0.6);
+    if (inNow) { attending.push(live); liveFamilies++; }
+    if (!attending.length) continue;
+    // The desk's first check-in gives the parent a free kids registration: a named place and ticket per child.
+    const { regLines } = addRegistration(event, f.parent, [line(option, f.children.length, {
+      attendees: f.children.map(c => ({ name: `${c.firstName} ${c.lastName}`, dateOfBirth: c.dateOfBirth, gender: c.gender, parentName: f.parent.name, parentEmail: f.parent.email })),
+    })], { createdAt: addTime(attending[0].startsAt, -25 * MINUTE) });
+    const attendees = regLines[0].attendees;
+    for (const s of attending) {
+      const code = add('kidsPickupCode', { id: uuidv4(), eventId: event.id, occasion: s.id, code: kidsCode(codes.get(s.id)), familyId: f.family.id, createdAt: addTime(s.startsAt, -int(10, 20) * MINUTE) });
+      const isLive = s === live;
+      f.children.forEach((c, i) => {
+        if (!chance(0.92)) return;
+        const at = isLive
+          ? within(addTime(NOW, -50 * MINUTE), addTime(NOW, -5 * MINUTE))
+          : within(addTime(s.startsAt, -20 * MINUTE), addTime(s.startsAt, 10 * MINUTE));
+        const ticket = rows.ticket.find(t => t.attendeeId === attendees[i].id);
+        const desk = pick(staffTeam);
+        add('kidsCheckIn', {
+          id: uuidv4(), eventId: event.id, occasion: s.id, sessionId: s.id, childId: c.id, childName: `${c.firstName} ${c.lastName}`,
+          roomId: roomFor(ageAt(c.dateOfBirth, s.startsAt)).id, pickupCodeId: code.id, attendeeId: attendees[i].id, ticketId: ticket.id,
+          checkedInAt: at, checkedInById: desk.id,
+          checkedOutAt: isLive ? null : within(addTime(s.endsAt, -5 * MINUTE), addTime(s.endsAt, 15 * MINUTE)),
+          checkedOutById: isLive ? null : pick(staffTeam).id,
+          collectedBy: isLive ? null : chance(0.85) ? f.parent.name : 'Authorised adult', offline: false,
+        });
+        add('ticketUsage', { id: uuidv4(), ticketId: ticket.id, scannedById: desk.id, scannedAt: at, sessionId: s.id, quantityRedeemed: 1 });
+        if (!c.lastCheckInAt || at > c.lastCheckInAt) c.lastCheckInAt = at;
+      });
+    }
+  }
+  for (const s of [...held, live]) {
+    const isLive = s === live;
+    if (isLive && live.startsAt > NOW) continue;
+    for (const room of rooms) {
+      for (const leader of shuffle(staffTeam).slice(0, int(1, 2))) {
+        add('kidsRoomDuty', {
+          id: uuidv4(), roomId: room.id, occasion: s.id, userId: leader.id, fromRoster: false,
+          startedAt: isLive ? addTime(NOW, -55 * MINUTE) : addTime(s.startsAt, -15 * MINUTE),
+          endedAt: isLive ? null : addTime(s.endsAt, 10 * MINUTE),
+        });
+      }
+    }
+  }
+  kidsChurches.push({ event, sessions, rooms });
+  return [event];
+}
+
+// ─── Volunteer rosters ───────────────────────────────────────────────────────
+
+/**
+ * Serving roles with people on them. `roles`: [name, needed, room?]. For a held session or event
+ * the places are filled and most checked in (QR); later ones are partly signed up. Reminders are
+ * marked as sent, so the reminder job doesn't email demo people.
+ */
+function addRoster(people, event, { session = null, roles, rooms = [] }) {
+  const start = session ? session.startsAt : event.startDate;
+  const held = (session ? session.endsAt : event.endDate) < NOW;
+  const daysAway = (start - NOW) / DAY;
+  const pool = shuffle(people.everyone);
+  const slots = [];
+  roles.forEach(([name, needed, roomName], order) => {
+    const role = add('servingRole', {
+      id: uuidv4(), eventId: event.id, sessionId: session ? session.id : null, name, description: null, needed,
+      startsAt: null, endsAt: null, kidsRoomId: roomName ? rooms.find(r => r.name === roomName)?.id || null : null,
+      order, createdAt: addTime(NOW, -25 * DAY), updatedAt: NOW,
+    });
+    const filled = held ? needed : daysAway < 10 ? int(Math.max(0, needed - 1), needed) : int(0, Math.max(0, needed - 1));
+    for (const user of pool.splice(0, filled)) {
+      const checked = held && chance(0.9);
+      // Most scan the QR code themselves; now and then a staff member ticks them in.
+      const method = checked ? (chance(0.85) ? 'qr' : 'manual') : null;
+      slots.push(add('volunteerSlot', {
+        id: uuidv4(), roleId: role.id, userId: user.id, assignedById: chance(0.3) ? staffTeam[0].id : null,
+        checkedInAt: checked ? within(addTime(start, -40 * MINUTE), addTime(start, -5 * MINUTE)) : null,
+        checkedInById: method === 'qr' ? user.id : method ? pick(staffTeam).id : null, checkInMethod: method,
+        remindedAt: held ? addTime(start, -DAY) : NOW, registrationId: null, createdAt: pastDate(20, 1),
+      }));
+    }
+  });
+  return slots;
+}
+
+function buildVolunteers(people, built) {
+  for (const { event, sessions, rooms } of kidsChurches) {
+    event.volunteerCheckInToken = hex();
+    const kidsRoles = [['Welcome desk', 3], ['Nursery leader', 2, 'Nursery'], ['Little Ones leader', 2, 'Little Ones'], ['Explorers leader', 2, 'Explorers'], ['Pre-teens leader', 1, 'Pre-teens']];
+    const lastHeld = sessions.filter(s => s.endsAt < NOW).pop();
+    const coming = sessions.filter(s => s.startsAt > NOW).slice(0, 2);
+    if (lastHeld) addRoster(people, event, { session: lastHeld, roles: kidsRoles, rooms });
+    coming.forEach((session, i) => {
+      const slots = addRoster(people, event, { session, roles: kidsRoles, rooms });
+      // Someone can't make the next Sunday and has asked for cover.
+      if (i === 0 && slots.length) {
+        const slot = slots[0];
+        add('volunteerSwap', { id: uuidv4(), slotId: slot.id, roleId: slot.roleId, fromUserId: slot.userId, toUserId: null, note: 'Away for a family wedding — can anyone take this?', status: 'open', createdAt: pastDate(2) });
+      }
+    });
+  }
+  const dayEvent = built.find(e => e.title === 'Family Fun Day');
+  if (dayEvent) {
+    dayEvent.volunteerCheckInToken = hex();
+    addRoster(people, dayEvent, { roles: [['Parking marshals', 4], ['Welcome & info table', 3], ['First aid', 1], ['Coffee bar', 3], ['Jumping castle supervisors', 2]] });
+  }
+}
+
+/** The extras of the chosen profile, in order; returns the upcoming events they add. */
+function buildExtras(people, built) {
+  const out = [];
+  const has = (x) => profile.extras.includes(x);
+  if (has('series')) out.push(...buildSeries(people));
+  if (has('courses')) out.push(...buildCourses(people));
+  if (has('conference')) out.push(...buildLeadershipConference(people));
+  if (has('kids')) {
+    if (profile.campuses) for (const c of campuses.slice(0, 2)) out.push(...buildKidsChurch(people, c));
+    else out.push(...buildKidsChurch(people));
+  }
+  if (has('volunteers')) buildVolunteers(people, built.concat(out));
+  return out;
+}
+
+function listProfiles() {
+  console.log('\nDemo profiles — npm run demo:<name> (from the repo root):\n');
+  for (const [name, p] of Object.entries(PROFILES)) {
+    console.log(`  ${name.padEnd(12)} ${p.title}`);
+    for (const line of p.about) console.log(`  ${''.padEnd(12)}   ${line}`);
+    console.log('');
+  }
+}
+
 // ─── Funnel analytics ────────────────────────────────────────────────────────
 
 const SOURCES = { direct: 30, whatsapp: 35, facebook: 18, instagram: 10, email: 7 };
@@ -1198,7 +1740,8 @@ function buildAnalytics() {
   const { sessionsFrom, rollupRows, RAW_DAYS } = require('../src/utils/analytics');
   const rawCutoff = addTime(NOW, -RAW_DAYS * DAY);
 
-  for (const event of rows.event) {
+  // Hidden events (kids church) aren't shown publicly, so nobody "visits" them.
+  for (const event of rows.event.filter(e => !e.isHidden)) {
     const raw = [];
     const session = (stages, at) => {
       const sessionId = uuidv4();
@@ -1242,10 +1785,25 @@ function buildAnalytics() {
 
 async function clearData(tx) {
   const tables = await tx.$queryRaw`SELECT tablename FROM pg_tables WHERE schemaname = current_schema()`;
-  const toClear = tables.map(t => t.tablename).filter(t => !KEEP_TABLES.has(t));
+  // Tables the User table points at (e.g. Campus via homeCampusId): TRUNCATE ... CASCADE on them
+  // would truncate User too — and with it the admin we keep — so their rows are deleted instead,
+  // after the admin's links to them are cleared.
+  const userRefs = await tx.$queryRaw`
+    SELECT DISTINCT ref.relname AS table, att.attname AS column
+    FROM pg_constraint c
+    JOIN pg_class src ON src.oid = c.conrelid
+    JOIN pg_class ref ON ref.oid = c.confrelid
+    JOIN pg_attribute att ON att.attrelid = c.conrelid AND att.attnum = ANY (c.conkey)
+    WHERE c.contype = 'f' AND src.relname = 'User' AND ref.relname <> 'User'`;
+  const deleteInstead = new Set(userRefs.map(r => r.table));
+  const toClear = tables.map(t => t.tablename).filter(t => !KEEP_TABLES.has(t) && !deleteInstead.has(t));
   if (toClear.length) {
     await tx.$executeRawUnsafe(`TRUNCATE TABLE ${toClear.map(t => `"${t}"`).join(', ')} CASCADE`);
   }
+  if (userRefs.length) {
+    await tx.$executeRawUnsafe(`UPDATE "User" SET ${[...new Set(userRefs.map(r => `"${r.column}" = NULL`))].join(', ')}`);
+    for (const table of deleteInstead) await tx.$executeRawUnsafe(`DELETE FROM "${table}"`);
+  }
   // Their password resets, 2FA codes and trusted devices go with them (onDelete: Cascade).
   const { count } = await tx.user.deleteMany({ where: { id: { not: admin.id } } });
   await tx.securityEvent.deleteMany({ where: { OR: [{ userId: null }, { userId: { not: admin.id } }] } });
@@ -1269,6 +1827,7 @@ function describeDatabase() {
 }
 
 async function confirm(admin) {
+  console.log(`\nDemo profile "${PROFILE_NAME}": ${profile.title}`);
   if (SKIP_PROMPT) return true;
   console.log(`\nThis will DELETE all events, registrations, payments, tickets, coupons and users`);
   console.log(`in ${describeDatabase()}, keeping only the site settings and ${admin.email}.`);
@@ -1279,6 +1838,13 @@ async function confirm(admin) {
 }
 
 async function main() {
+  if (LIST_ONLY) { listProfiles(); return; }
+  if (!profile) {
+    console.error(`Unknown demo profile "${PROFILE_NAME}". Choose one of: ${Object.keys(PROFILES).join(', ')}.`);
+    listProfiles();
+    process.exitCode = 1;
+    return;
+  }
   admin = await prisma.user.findFirst({ where: { email: { equals: ADMIN_EMAIL, mode: 'insensitive' } } });
   if (!admin) {
     console.error(`Admin account ${ADMIN_EMAIL} was not found — nothing was changed.`);
@@ -1295,15 +1861,11 @@ async function main() {
 
   passwordHash = await bcrypt.hash(DEMO_PASSWORD, 10);
   const people = buildPeople();
-  const events = [
-    buildMensBreakfast(people),
-    buildFamilyFunDay(people),
-    buildWomensConference(people),
-    buildYouthCamp(people),
-    buildCarols(people),
-    buildMarriageWeekend(people),
-  ];
+  if (profile.campuses) buildCampuses();
+  const events = profile.upcoming.map(key => UPCOMING[key](people));
+  events.push(...buildExtras(people, events));
   buildPastEvents(people);
+  if (profile.campuses) assignCampuses();
   buildAnalytics();
 
   const cleared = await prisma.$transaction(async (tx) => {
@@ -1311,6 +1873,13 @@ async function main() {
     for (const model of INSERT_ORDER) {
       if (rows[model] && rows[model].length) await tx[model].createMany({ data: rows[model] });
     }
+    if (profile.campuses) await scopeStaff(tx);
+    // Campuses on for the multi-campus demo, off for the others (site settings are kept).
+    await tx.appSetting.upsert({
+      where: { key: 'campuses_enabled' },
+      update: { value: profile.campuses ? 'true' : 'false' },
+      create: { key: 'campuses_enabled', value: profile.campuses ? 'true' : 'false' },
+    });
     return result;
   }, { maxWait: 10 * 1000, timeout: 5 * 60 * 1000 });
   clearScheduledEmails();
@@ -1348,7 +1917,17 @@ async function main() {
     ].filter(Boolean).join(', ');
     console.log(`  ${event.startDate.toDateString().padEnd(16)} ${event.title.padEnd(34)} ${String(regs).padStart(3)} registrations, ${String(scans).padStart(3)} check-ins — ${CASHUP_LABELS[cashup.close]}${notes ? ` (${notes})` : ''}`);
   }
-  console.log(`\nCreated ${count('user')} users, ${count('payment')} payments, ${count('ticket')} tickets, ${count('ticketUsage')} check-ins, ${count('attendee')} named campers, ${count('feedbackResponse')} feedback responses, ${count('analyticsEvent') + count('analyticsDaily')} funnel rows.`);
+  console.log(`\nCreated ${count('user')} users, ${count('payment')} payments, ${count('ticket')} tickets, ${count('ticketUsage')} check-ins, ${count('attendee')} named attendees, ${count('feedbackResponse')} feedback responses, ${count('analyticsEvent') + count('analyticsDaily')} funnel rows.`);
+  const extras = [
+    count('campus') && `${count('campus')} campuses (on), 2 campus-limited staff`,
+    count('eventSeries') && `${count('eventSeries')} series with ${count('seriesFollow')} followers, ${count('seasonPassPurchase')} season passes sold`,
+    count('eventSession') && `${count('eventSession')} sessions`,
+    count('certificate') && `${count('certificate')} certificates`,
+    count('family') && `${count('family')} families, ${count('child')} children, ${count('kidsCheckIn')} kids check-ins`,
+    count('servingRole') && `${count('servingRole')} serving roles, ${count('volunteerSlot')} volunteers rostered, ${count('volunteerSwap')} cover request`,
+  ].filter(Boolean);
+  if (extras.length) console.log(`Also: ${extras.join('; ')}.`);
+  console.log(`Campuses are ${profile.campuses ? 'ON' : 'off'} — restart the backend so it picks the setting up.`);
   console.log(`\nKept: site settings and ${admin.email}.`);
   console.log(`Demo staff logins (password ${DEMO_PASSWORD}):`);
   for (const s of staffTeam) console.log(`  ${s.role.padEnd(10)} ${s.email}`);

backend/src/config/db.js

@@ -3,7 +3,7 @@ const { PrismaPg } = require('@prisma/adapter-pg');
 
 // Prisma 7 talks to Postgres through the node-postgres driver adapter instead of
 // the old Rust engine. pg has no connect timeout by default; 5s matches Prisma 5.
-function createPrismaClient() {
+function createBaseClient() {
   const adapter = new PrismaPg({
     connectionString: process.env.DATABASE_URL,
     connectionTimeoutMillis: 5000,
@@ -11,6 +11,86 @@ function createPrismaClient() {
   return new PrismaClient({ adapter });
 }
 
+/**
+ * Outbound webhooks (utils/webhooks.js) notice what happens here, whichever code path does it:
+ * registrations made, paid or cancelled, payments and refunds, check-ins, new accounts, events
+ * becoming public. Noticing only queues; the record is read again before anything is sent, so a
+ * transaction that rolls back sends nothing. A failure here never affects the write itself.
+ */
+function withWebhooks(base) {
+  const notice = (type, id) => {
+    try { require('../utils/webhooks').notice(type, id); } catch (e) { console.warn('[webhooks] notice:', e?.message || e); }
+  };
+  const isPublic = e => !!e && e.isActive !== false && !e.isHidden;
+  // The status before an update (read outside the caller's transaction: the committed value).
+  const before = (model, where, select) => (where?.id ? base[model].findUnique({ where: { id: where.id }, select }).catch(() => null) : Promise.resolve(null));
+
+  return base.$extends({
+    query: {
+      registration: {
+        async create({ args, query }) {
+          const r = await query(args);
+          if (r?.id) {
+            notice('registration.created', r.id);
+            if (r.status === 'paid') notice('registration.paid', r.id);
+          }
+          return r;
+        },
+        async update({ args, query }) {
+          const status = args?.data?.status;
+          if (status !== 'paid' && status !== 'cancelled') return query(args);
+          const prev = await before('registration', args.where, { status: true });
+          const r = await query(args);
+          if (r?.id && prev && prev.status !== status) notice(status === 'paid' ? 'registration.paid' : 'registration.cancelled', r.id);
+          return r;
+        },
+      },
+      payment: {
+        async create({ args, query }) {
+          const p = await query(args);
+          // Applying an earlier donation to an order isn't new money (see cashupUtils.isDonationLeg).
+          const leg = p && !p.isDonation && p.originalPaymentId && p.amount > 0;
+          if (p?.id && !leg && p.amount !== 0) notice(p.amount < 0 ? 'payment.refunded' : 'payment.received', p.id);
+          return p;
+        },
+      },
+      ticketUsage: {
+        async create({ args, query }) {
+          const u = await query(args);
+          if (u?.id) notice('ticket.checked_in', u.id);
+          return u;
+        },
+      },
+      user: {
+        async create({ args, query }) {
+          const u = await query(args);
+          if (u?.id) notice('user.created', u.id);
+          return u;
+        },
+      },
+      event: {
+        async create({ args, query }) {
+          const e = await query(args);
+          if (e?.id && isPublic(e)) notice('event.published', e.id);
+          return e;
+        },
+        async update({ args, query }) {
+          const touches = args?.data && ('isActive' in args.data || 'isHidden' in args.data);
+          if (!touches) return query(args);
+          const prev = await before('event', args.where, { isActive: true, isHidden: true });
+          const e = await query(args);
+          if (e?.id && prev && !isPublic(prev) && isPublic(e)) notice('event.published', e.id);
+          return e;
+        },
+      },
+    },
+  });
+}
+
+function createPrismaClient() {
+  return withWebhooks(createBaseClient());
+}
+
 const prisma = createPrismaClient();
 
 module.exports = prisma;

backend/src/controllers/adminAuditController.js

@@ -6,8 +6,8 @@ const { safeErrorMessage } = require('../utils/errorUtils');
 // @access Admin
 const listAuditLog = async (req, res) => {
   try {
-    const { page, limit, actorId, action, from, to } = req.query;
-    const result = await getAdminAuditLog({ page, limit, actorId, action, from, to });
+    const { page, limit, actorId, action, role, from, to, search } = req.query;
+    const result = await getAdminAuditLog({ page, limit, actorId, action, role, from, to, search });
     res.json(result);
   } catch (e) {
     res.status(500).json({ message: safeErrorMessage(e) });

backend/src/controllers/attendanceController.js

@@ -1,4 +1,5 @@
-const ExcelJS = require('exceljs');
+// ExcelTS: a maintained TypeScript port of exceljs (same API, no dependencies).
+const ExcelJS = require('@cj-tech-master/excelts');
 const PDFDocument = require('pdfkit');
 const prisma = require('../config/db');
 const { safeErrorMessage } = require('../utils/errorUtils');

backend/src/controllers/costController.js

@@ -1,177 +1,44 @@
-const prisma = require('../config/db');
-const { v4: uuidv4 } = require('uuid');
+// Planned event costs (cashup and the profit report). Shared with /api/v2 (services/setup.ts, 1.51.8).
+const setup = require('../services/setup');
 const { safeErrorMessage } = require('../utils/errorUtils');
-const { assertEventOpen, ALL_METHODS } = require('../utils/cashupUtils');
 
-function normalizePaidFromMethod(value) {
-  if (value === undefined) return undefined;
-  if (value === null || value === '') return null;
-  if (!ALL_METHODS.includes(value)) {
-    throw new Error("paidFromMethod must be one of 'cash', 'card', 'eft', 'other', or null");
-  }
-  return value;
-}
+const fail = (res, error) => res.status(error.statusCode || 400).json({ message: safeErrorMessage(error) });
 
 // @desc    List costs for an event
 // @route   GET /api/events/:eventId/costs
 // @access  Private/Supervisor
 const getEventCosts = async (req, res) => {
   try {
-    const costs = await prisma.eventCost.findMany({
-      where: { eventId: req.params.eventId },
-      include: { eventOption: { select: { id: true, name: true } } },
-      orderBy: { createdAt: 'asc' }
-    });
-    res.json(costs);
-  } catch (error) {
-    res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(error) });
-  }
+    res.json(await setup.listCosts(req.params.eventId));
+  } catch (error) { fail(res, error); }
 };
 
 // @desc    Create a cost for an event
 // @route   POST /api/events/:eventId/costs
-// @access  Private/Supervisor
+// @access  Private/Admin
 const createEventCost = async (req, res) => {
   try {
-    const { eventId } = req.params;
-    const { label, costType, amount, eventOptionId, notes, paidFromMethod } = req.body;
-
-    await assertEventOpen(eventId, res);
-
-    if (!label || !String(label).trim()) {
-      res.status(400);
-      throw new Error('Label is required');
-    }
-    if (costType !== 'once_off' && costType !== 'per_item') {
-      res.status(400);
-      throw new Error("costType must be 'once_off' or 'per_item'");
-    }
-    const amt = parseFloat(amount);
-    if (!(amt >= 0)) {
-      res.status(400);
-      throw new Error('Amount must be a non-negative number');
-    }
-    if (costType === 'per_item' && !eventOptionId) {
-      res.status(400);
-      throw new Error('eventOptionId is required for per-item costs');
-    }
-    if (costType === 'per_item') {
-      const option = await prisma.eventOption.findUnique({ where: { id: eventOptionId } });
-      if (!option || option.eventId !== eventId) {
-        res.status(404);
-        throw new Error('Ticket type not found for this event');
-      }
-    }
-
-    const cost = await prisma.eventCost.create({
-      data: {
-        id: uuidv4(),
-        eventId,
-        label: String(label).trim(),
-        costType,
-        amount: amt,
-        eventOptionId: costType === 'per_item' ? eventOptionId : null,
-        paidFromMethod: normalizePaidFromMethod(paidFromMethod) ?? null,
-        notes: notes || null
-      },
-      include: { eventOption: { select: { id: true, name: true } } }
-    });
-
-    res.status(201).json(cost);
-  } catch (error) {
-    res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(error) });
-  }
+    res.status(201).json(await setup.createCost(req.params.eventId, req.body || {}));
+  } catch (error) { fail(res, error); }
 };
 
 // @desc    Update a cost
 // @route   PUT /api/costs/:id
-// @access  Private/Supervisor
+// @access  Private/Admin
 const updateEventCost = async (req, res) => {
   try {
-    const existing = await prisma.eventCost.findUnique({ where: { id: req.params.id } });
-    if (!existing) {
-      res.status(404);
-      throw new Error('Cost not found');
-    }
-
-    await assertEventOpen(existing.eventId, res);
-
-    const { label, costType, amount, eventOptionId, notes, paidFromMethod } = req.body;
-    const nextCostType = costType !== undefined ? costType : existing.costType;
-    if (nextCostType !== 'once_off' && nextCostType !== 'per_item') {
-      res.status(400);
-      throw new Error("costType must be 'once_off' or 'per_item'");
-    }
-
-    const nextEventOptionId = nextCostType === 'per_item'
-      ? (eventOptionId !== undefined ? eventOptionId : existing.eventOptionId)
-      : null;
-    if (nextCostType === 'per_item') {
-      if (!nextEventOptionId) {
-        res.status(400);
-        throw new Error('eventOptionId is required for per-item costs');
-      }
-      const option = await prisma.eventOption.findUnique({ where: { id: nextEventOptionId } });
-      if (!option || option.eventId !== existing.eventId) {
-        res.status(404);
-        throw new Error('Ticket type not found for this event');
-      }
-    }
-
-    let nextAmount = existing.amount;
-    if (amount !== undefined) {
-      const amt = parseFloat(amount);
-      if (!(amt >= 0)) {
-        res.status(400);
-        throw new Error('Amount must be a non-negative number');
-      }
-      nextAmount = amt;
-    }
-
-    const nextPaidFromMethod = normalizePaidFromMethod(paidFromMethod);
-
-    const cost = await prisma.eventCost.update({
-      where: { id: req.params.id },
-      data: {
-        label: label !== undefined ? String(label).trim() : existing.label,
-        costType: nextCostType,
-        amount: nextAmount,
-        eventOptionId: nextEventOptionId,
-        paidFromMethod: nextPaidFromMethod !== undefined ? nextPaidFromMethod : existing.paidFromMethod,
-        notes: notes !== undefined ? notes : existing.notes
-      },
-      include: { eventOption: { select: { id: true, name: true } } }
-    });
-
-    res.json(cost);
-  } catch (error) {
-    res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(error) });
-  }
+    res.json(await setup.updateCost(req.params.id, req.body || {}));
+  } catch (error) { fail(res, error); }
 };
 
 // @desc    Delete a cost
 // @route   DELETE /api/costs/:id
-// @access  Private/Supervisor
+// @access  Private/Admin
 const deleteEventCost = async (req, res) => {
   try {
-    const existing = await prisma.eventCost.findUnique({ where: { id: req.params.id } });
-    if (!existing) {
-      res.status(404);
-      throw new Error('Cost not found');
-    }
-
-    await assertEventOpen(existing.eventId, res);
-
-    await prisma.eventCost.delete({ where: { id: req.params.id } });
+    await setup.deleteCost(req.params.id);
     res.json({ message: 'Cost deleted' });
-  } catch (error) {
-    res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(error) });
-  }
+  } catch (error) { fail(res, error); }
 };
 
-module.exports = {
-  getEventCosts,
-  createEventCost,
-  updateEventCost,
-  deleteEventCost
-};
+module.exports = { getEventCosts, createEventCost, updateEventCost, deleteEventCost };

backend/src/controllers/hubController.js

@@ -13,15 +13,56 @@ function compareVersions(a, b) {
   return 0;
 }
 
-/** An update request still waiting: until this site runs the version that was asked for. */
-function pendingUpdateRequest(version, requestedAt, requestedVersion) {
+/**
+ * An update request still waiting: until this site runs the version that was asked for.
+ * `outdated`: a newer version than the one asked for is out, so the request can be changed to it.
+ */
+function pendingUpdateRequest(version, requestedAt, requestedVersion, latestVersion = null) {
   if (!requestedAt || !requestedVersion || compareVersions(version, requestedVersion) >= 0) return null;
-  return { requestedAt, version: requestedVersion };
+  return { requestedAt, version: requestedVersion, outdated: !!latestVersion && compareVersions(latestVersion, requestedVersion) > 0 };
+}
+
+const str = (v, max) => String(v ?? '').slice(0, max);
+
+/** What's new in each version newer than this one (from the Hub), newest first. */
+function newerReleases(releases, version) {
+  return (releases || [])
+    .filter(r => r && /^\d+\.\d+\.\d+$/.test(String(r.version)) && compareVersions(r.version, version) > 0)
+    .sort((a, b) => compareVersions(b.version, a.version))
+    .map(r => ({ version: r.version, releasedAt: r.releasedAt || null, urgent: !!r.urgent, notes: str(r.notes, 20000) }));
+}
+
+/**
+ * "Not now" holds until a newer version than the one put off comes out. Urgent updates (security or
+ * serious bug fixes) can't be put off.
+ */
+function updateSnoozed({ latestVersion, snoozedVersion, urgent }) {
+  return !!(latestVersion && snoozedVersion && !urgent && compareVersions(snoozedVersion, latestVersion) >= 0);
+}
+
+const NOTICE_LEVELS = new Set(['info', 'maintenance', 'warning']);
+
+/** The provider's notices showing now: started (or no start) and not ended. */
+function activeNotices(notices, now = new Date()) {
+  return (notices || [])
+    .filter(n => n && n.id && (!n.startsAt || new Date(n.startsAt) <= now) && (!n.endsAt || new Date(n.endsAt) > now))
+    .map(n => ({
+      id: str(n.id, 64),
+      level: NOTICE_LEVELS.has(n.level) ? n.level : 'info',
+      title: str(n.title, 120),
+      message: str(n.message, 2000),
+      startsAt: n.startsAt || null,
+      endsAt: n.endsAt || null,
+      updatedAt: n.updatedAt || null,
+    }));
 }
 
 /** What the admin pages show: licence state, Hub connection, version and update. */
 async function statusPayload({ fresh = false } = {}) {
   const s = await licenceStatus({ fresh });
+  const releases = newerReleases(s.releases, APP_VERSION);
+  const updateAvailable = !!(s.latestVersion && compareVersions(APP_VERSION, s.latestVersion) < 0);
+  const urgentUpdate = updateAvailable && releases.some(r => r.urgent);
   return {
     state: s.state,
     readOnly: s.readOnly,
@@ -45,8 +86,12 @@ async function statusPayload({ fresh = false } = {}) {
     lastError: s.lastError,
     version: APP_VERSION,
     latestVersion: s.latestVersion,
-    updateAvailable: !!(s.latestVersion && compareVersions(APP_VERSION, s.latestVersion) < 0),
-    updateRequest: pendingUpdateRequest(APP_VERSION, s.updateRequestedAt, s.updateRequestedVersion),
+    updateAvailable,
+    urgentUpdate,
+    updateSnoozed: updateAvailable && updateSnoozed({ latestVersion: s.latestVersion, snoozedVersion: s.updateSnoozedVersion, urgent: urgentUpdate }),
+    releases,
+    updateRequest: pendingUpdateRequest(APP_VERSION, s.updateRequestedAt, s.updateRequestedVersion, s.latestVersion),
+    notices: activeNotices(s.notices),
   };
 }
 
@@ -97,8 +142,11 @@ const heartbeatNow = async (req, res) => {
 const requestUpdate = async (req, res) => {
   try {
     const result = await hub.requestUpdate();
-    if (!result.alreadyRequested) {
-      logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'hub_update_requested', targetType: 'hub', metadata: { from: APP_VERSION, to: result.version }, ip: getClientIp(req) });
+    if (!result.alreadyRequested || result.changed) {
+      logAdminAction({
+        actorId: req.user.id, actorRole: req.user.role, action: 'hub_update_requested', targetType: 'hub',
+        metadata: { from: APP_VERSION, to: result.version, ...(result.changed ? { changedFrom: result.previousVersion || null } : {}) }, ip: getClientIp(req),
+      });
     }
     res.json(await statusPayload({ fresh: true }));
   } catch (e) {
@@ -107,4 +155,49 @@ const requestUpdate = async (req, res) => {
   }
 };
 
-module.exports = { getStatus, connect, heartbeatNow, requestUpdate, statusPayload, compareVersions, pendingUpdateRequest };
+// @desc    Withdraw the update request (the provider is told not to update after all)
+// @route   POST /api/hub/update-request/cancel
+// @access  Private/Admin
+const cancelUpdateRequest = async (req, res) => {
+  try {
+    await hub.cancelUpdateRequest();
+    logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: 'hub_update_request_withdrawn', targetType: 'hub', metadata: { version: APP_VERSION }, ip: getClientIp(req) });
+    res.json(await statusPayload({ fresh: true }));
+  } catch (e) {
+    const status = e.statusCode && e.statusCode < 500 && e.code !== 'INSTALL_NOT_FOUND' ? e.statusCode : 502;
+    res.status(status).json({ message: e.message || safeErrorMessage(e), code: e.code });
+  }
+};
+
+// @desc    "Not now": no update reminders until a newer version is out (snooze: false turns them back on)
+// @route   POST /api/hub/update-snooze   body: { snooze }
+// @access  Private/Admin
+const snoozeUpdate = async (req, res) => {
+  try {
+    const snooze = req.body?.snooze !== false;
+    const current = await statusPayload({ fresh: true });
+    if (snooze) {
+      if (!current.updateAvailable) { res.status(400); throw new Error('There is no update to put off.'); }
+      if (current.urgentUpdate) { res.status(400); throw new Error('This update fixes a security or serious problem, so it can\'t be put off.'); }
+    }
+    await hub.snoozeUpdate(snooze ? current.latestVersion : null);
+    logAdminAction({ actorId: req.user.id, actorRole: req.user.role, action: snooze ? 'hub_update_snoozed' : 'hub_update_unsnoozed', targetType: 'hub', metadata: { version: current.latestVersion }, ip: getClientIp(req) });
+    res.json(await statusPayload({ fresh: true }));
+  } catch (e) {
+    res.status(res.statusCode === 200 ? 500 : res.statusCode).json({ message: safeErrorMessage(e) });
+  }
+};
+
+// @desc    The provider's notices showing now (banner for site admins and supervisors)
+// @route   GET /api/hub/notices
+// @access  Private/Supervisor
+const getNotices = async (req, res) => {
+  try {
+    const s = await licenceStatus();
+    res.json(activeNotices(s.notices));
+  } catch (e) {
+    res.status(500).json({ message: safeErrorMessage(e) });
+  }
+};
+
+module.exports = { getStatus, connect, heartbeatNow, requestUpdate, cancelUpdateRequest, snoozeUpdate, getNotices, statusPayload, compareVersions, pendingUpdateRequest, newerReleases, updateSnoozed, activeNotices };

backend/src/controllers/outboundWebhookController.js

@@ -0,0 +1,178 @@
+const prisma = require('../config/db');
+const { logAdminAction } = require('../utils/adminAudit');
+const { getClientIp } = require('../utils/requestUtils');
+const webhooks = require('../utils/webhooks');
+
+const fail = (res, error) => res.status(error.statusCode || 400).json({ message: error.message });
+
+const audit = (req, endpoint, action, metadata = {}) => logAdminAction({
+  actorId: req.user.id, actorRole: req.user.role, action: 'webhook_endpoint_changed', targetType: 'WebhookEndpoint', targetId: endpoint.id,
+  metadata: { action, name: endpoint.name, host: hostOf(endpoint.url), ...metadata }, ip: getClientIp(req),
+});
+
+function hostOf(url) {
+  try { return new URL(url).host; } catch { return null; }
+}
+
+/** What goes to an endpoint, in words, for its operator register entry. */
+function dataShared(events) {
+  const parts = [];
+  if (events.some(e => e.startsWith('registration.') || e === 'ticket.checked_in' || e.startsWith('payment.') || e === 'user.created')) {
+    parts.push('names, email addresses and phone numbers of people who register or have an account');
+  }
+  if (events.some(e => e.startsWith('registration.'))) parts.push('what they registered for and its status');
+  if (events.some(e => e.startsWith('payment.'))) parts.push('payment and refund amounts');
+  if (events.includes('ticket.checked_in')) parts.push('check-in times');
+  if (events.includes('event.published')) parts.push('published event details');
+  return parts.length ? `${parts.join('; ')}.` : 'Nothing yet (no event types chosen).';
+}
+
+function cleanEvents(list) {
+  const events = [...new Set((Array.isArray(list) ? list : []).map(String))].filter(t => webhooks.TYPES.has(t));
+  if (!events.length) throw webhooks.webhookError('Choose at least one thing to send');
+  return events;
+}
+
+function cleanName(name) {
+  const n = String(name || '').trim();
+  if (!n) throw webhooks.webhookError('Give the webhook a name, e.g. the service it goes to');
+  return n.slice(0, 100);
+}
+
+const view = e => ({
+  id: e.id, name: e.name, url: e.url, events: e.events, isActive: e.isActive, operatorId: e.operatorId,
+  lastSuccessAt: e.lastSuccessAt, lastFailureAt: e.lastFailureAt, createdAt: e.createdAt,
+});
+
+// @desc    Endpoints, the event types, and the last week's delivery counts per endpoint
+// @route   GET /api/outbound-webhooks
+// @access  Private/Admin
+const list = async (req, res) => {
+  try {
+    const endpoints = await prisma.webhookEndpoint.findMany({ orderBy: { createdAt: 'asc' } });
+    const since = new Date(Date.now() - 7 * 864e5);
+    const counts = await prisma.webhookDelivery.groupBy({ by: ['endpointId', 'status'], where: { createdAt: { gte: since } }, _count: { _all: true } });
+    res.json({
+      eventTypes: webhooks.EVENT_TYPES,
+      keepDays: webhooks.KEEP_DAYS,
+      endpoints: endpoints.map(e => ({
+        ...view(e),
+        lastWeek: Object.fromEntries(counts.filter(c => c.endpointId === e.id).map(c => [c.status, c._count._all])),
+      })),
+    });
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    Add an endpoint: the secret is in this answer only. Also added to the operator register.
+// @route   POST /api/outbound-webhooks  { name, url, events }
+// @access  Private/Admin
+const create = async (req, res) => {
+  try {
+    const name = cleanName(req.body?.name);
+    const url = webhooks.cleanUrl(req.body?.url);
+    const events = cleanEvents(req.body?.events);
+    const secret = webhooks.newSecret();
+    const u = new URL(url);
+    // POPIA: whoever receives this is an operator of the church's personal information.
+    const operator = await prisma.operator.create({
+      data: { name: `${name} (webhook)`, purpose: 'Receives notifications from this site through a webhook', dataShared: dataShared(events), website: u.origin },
+    }).catch(() => null);
+    const endpoint = await prisma.webhookEndpoint.create({ data: { name, url, events, secret: webhooks.encrypt(secret), operatorId: operator?.id || null } });
+    webhooks.forgetEndpoints();
+    audit(req, endpoint, 'created', { events });
+    res.status(201).json({ ...view(endpoint), secret });
+  } catch (error) { fail(res, error); }
+};
+
+// @route   PUT /api/outbound-webhooks/:id  { name?, url?, events?, isActive? }
+// @access  Private/Admin
+const update = async (req, res) => {
+  try {
+    const current = await prisma.webhookEndpoint.findUnique({ where: { id: req.params.id } });
+    if (!current) return res.status(404).json({ message: 'Webhook not found' });
+    const data = {};
+    if (req.body?.name !== undefined) data.name = cleanName(req.body.name);
+    if (req.body?.url !== undefined) data.url = webhooks.cleanUrl(req.body.url);
+    if (req.body?.events !== undefined) data.events = cleanEvents(req.body.events);
+    if (req.body?.isActive !== undefined) data.isActive = req.body.isActive !== false;
+    const endpoint = await prisma.webhookEndpoint.update({ where: { id: current.id }, data });
+    if (current.operatorId && (data.events || data.url || data.name || data.isActive !== undefined)) {
+      await prisma.operator.update({
+        where: { id: current.operatorId },
+        data: { name: `${endpoint.name} (webhook)`, dataShared: dataShared(endpoint.events), website: new URL(endpoint.url).origin, active: endpoint.isActive },
+      }).catch(() => {});
+    }
+    webhooks.forgetEndpoints();
+    audit(req, endpoint, 'updated', { changedKeys: Object.keys(data) });
+    res.json(view(endpoint));
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    Delete an endpoint and its delivery log; its operator entry is marked inactive
+// @route   DELETE /api/outbound-webhooks/:id
+// @access  Private/Admin
+const remove = async (req, res) => {
+  try {
+    const current = await prisma.webhookEndpoint.findUnique({ where: { id: req.params.id } });
+    if (!current) return res.status(404).json({ message: 'Webhook not found' });
+    await prisma.webhookEndpoint.delete({ where: { id: current.id } });
+    if (current.operatorId) await prisma.operator.update({ where: { id: current.operatorId }, data: { active: false } }).catch(() => {});
+    webhooks.forgetEndpoints();
+    audit(req, current, 'deleted');
+    res.json({ ok: true });
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    A new secret (the old one stops working at once); in this answer only
+// @route   POST /api/outbound-webhooks/:id/rotate-secret
+// @access  Private/Admin
+const rotateSecret = async (req, res) => {
+  try {
+    const current = await prisma.webhookEndpoint.findUnique({ where: { id: req.params.id } });
+    if (!current) return res.status(404).json({ message: 'Webhook not found' });
+    const secret = webhooks.newSecret();
+    await prisma.webhookEndpoint.update({ where: { id: current.id }, data: { secret: webhooks.encrypt(secret) } });
+    audit(req, current, 'secret_rotated');
+    res.json({ secret });
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    Send a "webhook.test" now and say what came back
+// @route   POST /api/outbound-webhooks/:id/test
+// @access  Private/Admin
+const test = async (req, res) => {
+  try {
+    if (!(await prisma.webhookEndpoint.findUnique({ where: { id: req.params.id }, select: { id: true } }))) return res.status(404).json({ message: 'Webhook not found' });
+    const d = await webhooks.sendTest(req.params.id);
+    res.json({ status: d?.status, statusCode: d?.lastStatusCode ?? null, error: d?.lastError || null });
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    An endpoint's deliveries, newest first (?status=failed to filter)
+// @route   GET /api/outbound-webhooks/:id/deliveries
+// @access  Private/Admin
+const deliveries = async (req, res) => {
+  try {
+    const where = { endpointId: req.params.id, ...(req.query.status ? { status: String(req.query.status) } : {}) };
+    // "Load older": the next page is everything before the last one shown.
+    const before = req.query.before ? new Date(String(req.query.before)) : null;
+    if (before && !Number.isNaN(before.getTime())) where.createdAt = { lt: before };
+    const rows = await prisma.webhookDelivery.findMany({
+      where, orderBy: { createdAt: 'desc' }, take: Math.min(200, parseInt(req.query.limit, 10) || 50),
+      select: { id: true, eventId: true, type: true, status: true, attempts: true, nextAttemptAt: true, lastStatusCode: true, lastError: true, deliveredAt: true, createdAt: true, payload: true },
+    });
+    res.json(rows);
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    Send a delivery again now
+// @route   POST /api/outbound-webhooks/deliveries/:id/resend
+// @access  Private/Admin
+const resend = async (req, res) => {
+  try {
+    const d = await webhooks.resend(req.params.id);
+    res.json({ status: d?.status, statusCode: d?.lastStatusCode ?? null, error: d?.lastError || null });
+  } catch (error) { fail(res, error); }
+};
+
+module.exports = { list, create, update, remove, rotateSecret, test, deliveries, resend, dataShared };

backend/src/controllers/paymentController.js

@@ -6,7 +6,6 @@ const { computeDonationRemaining } = require('../utils/donationUtils');
 const { logAdminAction } = require('../utils/adminAudit');
 const { getClientIp } = require('../utils/requestUtils');
 const payments = require('../payments');
-const { createRegistrationCheckout } = require('../payments/checkouts');
 const { emailTickets } = require('./ticketController');
 const { safeErrorMessage } = require('../utils/errorUtils');
 const { assertEventOpen, assertRegistrationEventOpen } = require('../utils/cashupUtils');
@@ -354,7 +353,15 @@ const getPayments = async (req, res) => {
     // Campus-scoped supervisors: payments for events they can see (through the payment's event or
     // its registration's), so unlinked donations aren't listed for them.
     const scopeW = require('../utils/campusScope').eventWhere(await require('../utils/campusScope').scopeFor(req));
-    const where = Object.keys(scopeW).length ? { OR: [{ event: scopeW }, { registration: { event: scopeW } }] } : {};
+    const scopeWhere = Object.keys(scopeW).length ? { OR: [{ event: scopeW }, { registration: { event: scopeW } }] } : {};
+    // Narrowing filters: ?userId= (one person's), ?from= (on or after, e.g. today's start),
+    // ?donations=1 (donations and the legs that apply them to registrations).
+    const filters = [];
+    if (req.query.userId) filters.push({ userId: String(req.query.userId) });
+    const from = req.query.from ? new Date(String(req.query.from)) : null;
+    if (from && !Number.isNaN(from.getTime())) filters.push({ createdAt: { gte: from } });
+    if (['1', 'true'].includes(String(req.query.donations || ''))) filters.push({ OR: [{ isDonation: true }, { originalPaymentId: { not: null } }] });
+    const where = filters.length ? { AND: [scopeWhere, ...filters] } : scopeWhere;
     const [payments, total] = await prisma.$transaction([
       prisma.payment.findMany({ where, include, orderBy: { createdAt: 'desc' }, skip, take: limit }),
       prisma.payment.count({ where })
@@ -933,54 +940,14 @@ const createCheckout = async (req, res) => {
       throw new Error('Either registrationId or eventId is required');
     }
 
-    // A registration's balance
+    // A registration's balance (shared with POST /api/v2/registrations/:id/checkout)
     if (registrationId) {
-      const reg = await prisma.registration.findUnique({ where: { id: registrationId }, select: { userId: true, eventId: true, event: { select: { endDate: true } } } });
-      if (!reg) { res.status(404); throw new Error('Registration not found'); }
-      if (reg.userId !== userId && req.user.role !== 'admin' && req.user.role !== 'supervisor') {
-        res.status(403); throw new Error('Not authorized to create checkout for this registration');
-      }
-      // If event is in the past, block self-service payment (mirrors the registration-edit block)
-      if (req.user.role !== 'admin' && req.user.role !== 'supervisor' && reg.event?.endDate && new Date(reg.event.endDate).getTime() < Date.now()) {
-        res.status(400); throw new Error('This event has already ended; payment can no longer be made for this registration');
-      }
-      await assertEventOpen(reg.eventId, res);
-
-      // Refresh early-bird pricing — updates priceSnapshot if any tier has expired or sold out.
-      // Must run before the balance is worked out so the checkout charges the right price.
-      const { changed: priceChanged } = await refreshPricingForRegistration(registrationId);
-      if (priceChanged) {
-        const freshReg = await prisma.registration.findUnique({
-          where: { id: registrationId },
-          include: {
-            registrationOptions: { include: { eventOption: { include: { earlyBirdTiers: true } }, tranches: true } },
-            payments: true
-          }
-        });
-        const newTotal = computeRegistrationTotalDue(freshReg, new Date());
-        const totalPaid = (freshReg.payments || []).reduce((s, p) => s + p.amount, 0);
-        return res.status(200).json({
-          priceUpdated: true,
-          newTotal: Math.max(0, newTotal - totalPaid),
-          message: 'One or more early-bird prices have changed since your registration was created. Please review the updated total before proceeding.'
-        });
-      }
-
-      // Part of the balance (supervisor payments page)
-      if (amount && !isNaN(parseFloat(amount))) {
-        const result = await createRegistrationCheckout(registrationId, userId, { successUrl, cancelUrl, failureUrl, amount: parseFloat(amount), provider });
-        return res.status(200).json(result);
-      }
-
-      // Optional donation added at registration ("Donation amount" on the register form)
-      let donation = 0;
-      if (donationAmount !== undefined && donationAmount !== null && donationAmount !== '') {
-        donation = Math.round(parseFloat(donationAmount) * 100) / 100;
-        if (!(donation >= 0) || donation > 100000) { res.status(400); throw new Error('Invalid donation amount'); }
-        if (donation > 0 && donation < payments.MIN_ONLINE_AMOUNT) { res.status(400); throw new Error(`Minimum donation is R${payments.MIN_ONLINE_AMOUNT}`); }
-      }
-
-      const result = await createRegistrationCheckout(registrationId, userId, { successUrl, cancelUrl, failureUrl, donationAmount: donation, provider });
+      const { startRegistrationCheckout } = require('../services/payments');
+      const result = await startRegistrationCheckout(registrationId, req.user, {
+        amount: amount && !isNaN(parseFloat(amount)) ? parseFloat(amount) : null,
+        donationAmount: donationAmount === undefined || donationAmount === null || donationAmount === '' ? null : parseFloat(donationAmount),
+        successUrl, cancelUrl, failureUrl, provider,
+      });
       return res.status(200).json(result);
     }
 

backend/src/controllers/privacyAdminController.js

@@ -65,12 +65,30 @@ const getNoticeDraft = async (req, res) => {
       placeholders: notice.PLACEHOLDERS,
       versions: await versionList(),
       builtIn: notice.defaultSections(),
+      // Changes to the built-in text since this site last reviewed them (only once it publishes its own).
+      builtInUpdates: await notice.builtInUpdates(),
     });
   } catch (error) {
     fail(res, error);
   }
 };
 
+// @desc    The built-in text changes have been gone through (the editor stops listing them)
+// @route   POST /api/privacy/notice/builtin-reviewed
+// @access  Private/Admin
+const markBuiltInReviewed = async (req, res) => {
+  try {
+    await notice.markBuiltInReviewed();
+    logAdminAction({
+      actorId: req.user.id, actorRole: req.user.role, action: 'settings_updated', targetType: 'privacy_notice',
+      metadata: { builtInReviewed: notice.BUILT_IN_REVISION }, ip: getClientIp(req),
+    });
+    res.json({ builtInUpdates: [] });
+  } catch (error) {
+    fail(res, error);
+  }
+};
+
 // @desc    Save the draft (body.sections)
 // @route   PUT /api/privacy/notice/draft
 // @access  Private/Admin
@@ -425,6 +443,7 @@ const updateBreach = async (req, res) => {
 };
 
 module.exports = {
+  markBuiltInReviewed,
   getReadiness,
   getRetention,
   saveRetention,

backend/src/controllers/privacyController.js

@@ -227,12 +227,18 @@ const listRequests = async (req, res) => {
     const where = { selfService: false };
     if (status === 'open') where.status = 'open';
     else if (status === 'closed') where.status = { not: 'open' };
-    const rows = await prisma.dataRequest.findMany({
+    const q = String(req.query.search || '').trim().slice(0, 100);
+    if (q) where.OR = [{ name: { contains: q, mode: 'insensitive' } }, { email: { contains: q, mode: 'insensitive' } }];
+    // Closed requests pile up over the years, so they come a page at a time (newest first).
+    const limit = Math.min(200, Math.max(1, parseInt(req.query.limit, 10) || 50));
+    const page = Math.max(1, parseInt(req.query.page, 10) || 1);
+    const [rows, total] = await Promise.all([prisma.dataRequest.findMany({
       where,
       orderBy: status === 'open' ? { dueAt: 'asc' } : { createdAt: 'desc' },
-      take: 200,
+      take: limit,
+      skip: (page - 1) * limit,
       include: { handledBy: { select: { name: true } }, user: { select: { isActive: true, phoneNumber: true } } },
-    });
+    }), prisma.dataRequest.count({ where })]);
     const requests = await Promise.all(rows.map(async r => ({
       id: r.id, type: r.type, status: r.status, name: r.name, email: r.email, details: r.details, response: r.response,
       dueAt: r.dueAt, closedAt: r.closedAt, createdAt: r.createdAt, userId: r.userId,
@@ -240,8 +246,8 @@ const listRequests = async (req, res) => {
       overdue: r.status === 'open' && r.dueAt < new Date(),
       blockers: r.type === 'deletion' && r.status === 'open' && r.userId ? await privacy.deletionBlockers(r.userId) : [],
     })));
-    const openCount = status === 'open' ? requests.length : await prisma.dataRequest.count({ where: { selfService: false, status: 'open' } });
-    res.json({ requests, openCount });
+    const openCount = status === 'open' && !q ? total : await prisma.dataRequest.count({ where: { selfService: false, status: 'open' } });
+    res.json({ requests, openCount, total, page, limit, pages: Math.max(1, Math.ceil(total / limit)) });
   } catch (error) {
     fail(res, error);
   }

backend/src/controllers/registrationController.js

@@ -3,531 +3,33 @@ const { v4: uuidv4 } = require('uuid');
 const { generateTicketsForRegistration } = require('../utils/ticketUtils');
 const { emailTickets } = require('./ticketController');
 const { hashPassword } = require('../config/auth');
-const { resolveOptionPrice, resolveVariantTierPrice, computeRegistrationTotalDue, refreshPricingForRegistration, attachComputedTotals, attachComputedTotalsToList } = require('../utils/pricing');
+const { computeRegistrationTotalDue, refreshPricingForRegistration, attachComputedTotals, attachComputedTotalsToList } = require('../utils/pricing');
 const { assertEventOpen } = require('../utils/cashupUtils');
 const { logAdminAction } = require('../utils/adminAudit');
 const { getClientIp } = require('../utils/requestUtils');
-const { buildCouponLines, previewCoupon, applyCouponToRegistration, recalculateRegistrationDiscount, releaseRegistrationCoupons, describeCoupon } = require('../utils/coupons');
-const { lineKey, validateAttendees, createAttendees, namedPlacesByKey } = require('../utils/attendees');
+const { previewCoupon, applyCouponToRegistration, recalculateRegistrationDiscount, releaseRegistrationCoupons, describeCoupon } = require('../utils/coupons');
+const { validateAttendees, createAttendees, namedPlacesByKey } = require('../utils/attendees');
 const { findAccountByContact } = require('../utils/accountMatch');
-const { ensureConsentRequests } = require('../utils/consent');
-const { takenCount } = require('../utils/stock');
-const { findOfferByToken, queueWaitlist } = require('../utils/waitlist');
+const { 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.
-function queueConsentRequests(registrationId) {
-  ensureConsentRequests(registrationId).catch(e => console.error('[consent] Failed to send requests:', e?.message || e));
-}
-
-// Named attendees for API responses, with whether their ticket has been issued/used.
-const ATTENDEES_INCLUDE = {
-  orderBy: { order: 'asc' },
-  include: {
-    ticket: { select: { id: true, isUsed: true } },
-    // Latest consent request (youth events) — it decides check-in.
-    consentRequests: { orderBy: { createdAt: 'desc' }, take: 1, select: { id: true, status: true, respondedAt: true, lastSentAt: true, textVersion: true } },
-  },
-};
-
-const TICKET_DELIVERY = ['payer', 'each'];
-
-/**
- * Places each line will have once `requested` is added to `existingLines` — used to
- * check attendee names against what's actually being bought.
- */
-function placesAfter(existingLines, requested) {
-  const out = {};
-  // Picked-session lines take no attendee names.
-  for (const l of [...(existingLines || []), ...(requested || [])].filter(x => !x.sessionId)) {
-    const k = lineKey(l.eventOptionId, l.variantId);
-    out[k] = (out[k] || 0) + Number(l.quantity || 0);
-  }
-  return out;
-}
-
-// Active coupon on a registration, for API responses (the discount itself is
-// Registration.discountTotal).
-const ACTIVE_COUPONS_INCLUDE = {
-  where: { releasedAt: null },
-  select: { id: true, discountAmount: true, createdAt: true, coupon: { select: { id: true, code: true, type: true, value: true, description: true } } },
-};
+// Shared with POST /api/v2/registrations: the registration service (TypeScript, 1.51.1).
+const registrationService = require('../services/registrations');
+const {
+  queueConsentRequests, ATTENDEES_INCLUDE, TICKET_DELIVERY, placesAfter, ACTIVE_COUPONS_INCLUDE,
+  pendingCouponLines, priceRequestedOption, checkOptionStock, checkVariantStock, isStaffRole,
+} = registrationService;
 const { BUNDLE_APPS_INCLUDE } = require('../utils/bundles');
-const { registrationClosesAt, wholeCourseClosesAt, expandPickLines, assertSessionCapacity, isPickOption, mergeSessionIds } = require('../utils/sessions');
-
-/**
- * Coupon lines for options that haven't been saved yet, so a code can be checked
- * before anything is created. Mirrors buildCouponLines for one tranche per option.
- */
-function pendingCouponLines(event, resolvedOptions) {
-  return buildCouponLines({
-    registrationOptions: resolvedOptions.map(o => ({
-      eventOptionId: o.eventOptionId,
-      variantId: o.variantId || null,
-      quantity: o.quantity,
-      eventOption: event.eventOptions.find(eo => eo.id === o.eventOptionId),
-      tranches: [{ quantity: o.quantity, priceSnapshot: o.priceSnapshot, appliedTierId: o.appliedTierId }],
-    })),
-  });
-}
-
-/**
- * Price one requested option for this buyer: early-bird tiers, then variant/option price,
- * then the staff price for Staff and above. Returns { priceSnapshot, appliedTierId }.
- */
-async function priceRequestedOption(eventOption, variantId, qty, buyer) {
-  try {
-    const resolved = variantId
-      ? await resolveVariantTierPrice(eventOption, variantId, qty, buyer)
-      : await resolveOptionPrice(eventOption, qty, buyer);
-    return { priceSnapshot: resolved.price, appliedTierId: resolved.tierId };
-  } catch (e) {
-    const variant = variantId ? (eventOption.variants || []).find(v => v.id === variantId) : null;
-    const price = variant && variant.price !== null && variant.price !== undefined ? variant.price : eventOption.price;
-    return { priceSnapshot: Number(price || 0), appliedTierId: null };
-  }
-}
-
-/**
- * Check overall stock availability for an EventOption. Places held for live waitlist
- * offers count as taken, except the offer being claimed (`excludeEntryId`).
- * Returns { available: boolean, remaining: number|null }
- */
-async function checkOptionStock(option, requestedQty, excludeEntryId = null, sessionId = null) {
-  if (!option.stockLimit || option.stockLimit === 0) return { available: true, remaining: null };
-  const remaining = option.stockLimit - await takenCount({ eventOptionId: option.id, sessionId }, { excludeEntryId });
-  return { available: remaining >= requestedQty, remaining };
-}
-
-/**
- * Check stock availability for a specific variant (same rules as checkOptionStock).
- */
-async function checkVariantStock(variant, requestedQty, excludeEntryId = null, sessionId = null) {
-  if (!variant.stockLimit || variant.stockLimit === 0) return { available: true, remaining: null };
-  const remaining = variant.stockLimit - await takenCount({ eventOptionId: variant.eventOptionId, variantId: variant.id, sessionId }, { excludeEntryId });
-  return { available: remaining >= requestedQty, remaining };
-}
+const { expandPickLines, assertSessionCapacity, isPickOption, mergeSessionIds } = require('../utils/sessions');
 
 // @desc    Create a new registration
 // @route   POST /api/registrations
 // @access  Private
 const createRegistration = async (req, res) => {
   try {
-    const { eventId, options, guestName, guestEmail, guestPhone, couponCode, attendees, ticketDelivery, waitlistToken, analyticsSessionId } = req.body;
-
-    // Check if event exists
-    const canIncludeVariants = !!(prisma && prisma.optionVariant && typeof prisma.optionVariant.findMany === 'function');
-    const canIncludeTiers = !!(prisma && prisma.earlyBirdTier && typeof prisma.earlyBirdTier.findMany === 'function');
-    const optionInclude = canIncludeTiers
-      ? { earlyBirdTiers: true, ...(canIncludeVariants ? { variants: true } : {}) }
-      : true;
-    const event = await prisma.event.findUnique({
-      where: { id: eventId },
-      include: { eventOptions: optionInclude ? { include: optionInclude } : true, sessions: true }
-    });
-
-    if (!event) {
-      res.status(404);
-      throw new Error('Event not found');
-    }
-
-    if (!event.isActive) {
-      res.status(400);
-      throw new Error('Event is not active');
-    }
-
-    if (event.cashupStatus === 'closed') {
-      res.status(400);
-      throw new Error('This event is closed and no longer accepting registrations.');
-    }
-
-    // A waitlist claim link: its token identifies the person and releases the places
-    // held for them. It works without logging in, the same way a consent link does.
-    let waitlistOffer = null;
-    if (waitlistToken) {
-      waitlistOffer = await findOfferByToken(waitlistToken);
-      if (!waitlistOffer || waitlistOffer.eventId !== eventId) { res.status(400); throw new Error('This waitlist link is not valid.'); }
-      if (waitlistOffer.status !== 'offered') { res.status(400); throw new Error(`This waitlist offer has ${waitlistOffer.status === 'claimed' ? 'already been used' : 'expired'}.`); }
-      if (new Date(waitlistOffer.offerExpiresAt) < new Date()) { res.status(400); throw new Error('This waitlist offer has expired.'); }
-      if (req.user && req.user.id !== waitlistOffer.userId) { res.status(403); throw new Error('This waitlist offer belongs to someone else.'); }
-    }
-
-    // Enforce auth unless event explicitly opts out
-    const eventRequiresAuth = event.requiresAuth !== false;
-    if (eventRequiresAuth && !req.user && !waitlistOffer) {
-      res.status(401);
-      throw new Error('Authentication required for this event');
-    }
-
-    // Unauthenticated guest registration is only permitted for free events
-    if (!req.user && !waitlistOffer) {
-      const totalDueCheck = (event.eventOptions || []).reduce((sum, eo) => sum + (eo.price || 0), 0);
-      // Also check against the requested options specifically
-      const requestedTotal = (options || []).reduce((sum, opt) => {
-        const eo = event.eventOptions.find(o => o.id === opt.eventOptionId);
-        return sum + ((eo?.price || 0) * (opt.quantity || 1));
-      }, 0);
-      if (requestedTotal > 0) {
-        res.status(400);
-        throw new Error('Guest registration is only available for free events. Please create an account to pay for tickets.');
-      }
-    }
-
-    // Resolve userId — authenticated or guest
-    let userId;
-    if (req.user) {
-      userId = req.user.id;
-    } else if (waitlistOffer) {
-      userId = waitlistOffer.userId;
-    } else {
-      // Guest registration: find existing user by email or create inactive placeholder
-      if (!guestEmail || !guestName) {
-        res.status(400);
-        throw new Error('Name and email are required for unauthenticated registration');
-      }
-      const match = await findAccountByContact({ email: guestEmail, phone: guestPhone });
-      if (match.conflict) {
-        res.status(409);
-        throw new Error('This email and phone number belong to two different accounts. Please log in, or check your details.');
-      }
-      const existingGuest = match.user;
-      if (existingGuest) {
-        userId = existingGuest.id;
-      } else {
-        const newGuest = await prisma.user.create({
-          data: {
-            id: uuidv4(),
-            name: guestName,
-            email: guestEmail,
-            password: '',
-            phoneNumber: guestPhone || null,
-            isActive: false,
-            updatedAt: new Date(),
-          }
-        });
-        userId = newGuest.id;
-      }
-    }
-
-    // Enforce registration cutoff for public registrations (multi-day events close when
-    // the first session starts, or later with late joining — see utils/sessions.js).
-    const now = new Date();
-    if (now >= registrationClosesAt(event, event.sessions)) {
-      res.status(400);
-      throw new Error('Registration is closed for this event');
-    }
-
-    // Validate options
-    if (!options || !Array.isArray(options) || options.length === 0) {
-      res.status(400);
-      throw new Error('At least one option must be selected');
-    }
-
-    // "Pick sessions" options become one line per chosen session; whole-course tickets
-    // on such an event still close when the whole course does.
-    const lines = expandPickLines(event, options, { now });
-    // (An all-sessions ticket with sessions ticked is checked per session instead.)
-    if (event.attendanceMode === 'pick' && lines.some(l => !l.sessionId && !l.sessionIds?.length) && now >= wholeCourseClosesAt(event, event.sessions)) {
-      res.status(400);
-      throw new Error('Whole-course tickets are no longer on sale — choose the sessions you want instead.');
-    }
-    await assertSessionCapacity(event, lines, undefined, { excludeEntryId: waitlistOffer?.id });
-
-    // Validate each option and resolve prices / check stock.
-    // 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.
-    const resolvedOptions = await Promise.all(lines.map(async (option) => {
-      const eventOption = event.eventOptions.find(eo => eo.id === option.eventOptionId);
-      if (!eventOption) {
-        throw new Error(`Option with ID ${option.eventOptionId} not found for this event`);
-      }
-      if (!option.quantity || option.quantity < 1) {
-        throw new Error('Quantity must be at least 1');
-      }
-
-      const qty = option.quantity;
-
-      // Check overall option stock
-      try {
-        const stockCheck = await checkOptionStock(eventOption, qty, waitlistOffer?.id, option.sessionId);
-        if (!stockCheck.available) {
-          const err = new Error(`"${eventOption.name}" is sold out or does not have enough stock (${stockCheck.remaining ?? 0} remaining).`);
-          err.isStockError = true;
-          throw err;
-        }
-      } catch (e) {
-        if (e.isStockError) throw e; // propagate stock errors
-        // If stock check function fails (pre-migration), continue without stock check
-      }
-
-      // Check variant stock (if a variant is selected)
-      let variantId = option.variantId || null;
-      let variantPrice = null;
-      if (variantId && canIncludeVariants) {
-        const variant = (eventOption.variants || []).find(v => v.id === variantId);
-        if (!variant) {
-          throw new Error(`Variant not found for option "${eventOption.name}"`);
-        }
-        try {
-          const vStock = await checkVariantStock(variant, qty, waitlistOffer?.id, option.sessionId);
-          if (!vStock.available) {
-            const err = new Error(`Variant "${variant.name}" is sold out (${vStock.remaining ?? 0} remaining).`);
-            err.isStockError = true;
-            throw err;
-          }
-        } catch (e) {
-          if (e.isStockError) throw e;
-        }
-        variantPrice = variant.price; // null = use option price
-      }
-
-      // Resolve price: variant-level tiers take priority, then option-level tiers, then
-      // base prices, then the staff price for Staff and above.
-      let priceSnapshot = null;
-      let appliedTierId = null;
-      if (canIncludeTiers) {
-        const buyer = req.user || (waitlistOffer ? await prisma.user.findUnique({ where: { id: waitlistOffer.userId }, select: { id: true, role: true } }) : null);
-        ({ priceSnapshot, appliedTierId } = await priceRequestedOption(eventOption, variantId, qty, buyer));
-      } else {
-        priceSnapshot = variantPrice !== null && variantPrice !== undefined ? variantPrice : null;
-      }
-      if (priceSnapshot === null) priceSnapshot = eventOption.price;
-
-      return { ...option, variantId, appliedTierId, priceSnapshot };
-    }));
-
-    // Check a coupon code before anything is saved, so a bad code doesn't leave a
-    // half-made registration behind. It's applied (and re-checked under a lock) below.
-    if (couponCode) {
-      const buyer = req.user ? { id: req.user.id, role: req.user.role, email: req.user.email } : null;
-      await previewCoupon({ code: couponCode, eventId, user: buyer, lines: pendingCouponLines(event, resolvedOptions) });
-    }
-
-    // Check for existing non-cancelled registration for this user+event → merge instead
-    const existingReg = await prisma.registration.findFirst({
-      where: { userId, eventId, status: { not: 'cancelled' } },
-      include: { registrationOptions: true }
-    });
-
-    // Attendee names are checked against the places the registration will have after
-    // this purchase, counting names already given on an existing registration.
-    const cleanAttendees = validateAttendees(
-      event,
-      placesAfter(existingReg?.registrationOptions, resolvedOptions),
-      attendees,
-      existingReg ? await namedPlacesByKey(existingReg.id) : {}
-    );
-    if (ticketDelivery !== undefined && !TICKET_DELIVERY.includes(ticketDelivery)) {
-      res.status(400);
-      throw new Error("ticketDelivery must be 'payer' or 'each'");
-    }
-
-    let registration;
-    let isNewRegistration = false;
-    if (existingReg) {
-      // Merge: add a new price tranche per requested option into the existing registration.
-      // Never overwrite an existing row's priceSnapshot/quantity in place — that would blend
-      // tickets bought at different early-bird prices into a single (wrong) price. Each
-      // purchase gets its own tranche; the RegistrationOption row stays a maintained aggregate.
-      for (const opt of resolvedOptions) {
-        // Match on eventOptionId + variantId (+ session, for picked sessions) for correct row
-        const existing = existingReg.registrationOptions.find(
-          ro => ro.eventOptionId === opt.eventOptionId && (ro.variantId || null) === (opt.variantId || null) && (ro.sessionId || null) === (opt.sessionId || null)
-        );
-        if (existing) {
-          await prisma.$transaction([
-            prisma.registrationOptionTranche.create({
-              data: {
-                id: uuidv4(),
-                registrationOptionId: existing.id,
-                quantity: opt.quantity,
-                priceSnapshot: opt.priceSnapshot,
-                appliedTierId: opt.appliedTierId || null,
-              }
-            }),
-            prisma.registrationOption.update({
-              where: { id: existing.id },
-              data: { quantity: existing.quantity + opt.quantity, priceSnapshot: opt.priceSnapshot, appliedTierId: opt.appliedTierId || null, ...(existing.sessionId ? {} : { sessionIds: mergeSessionIds(existing.sessionIds, opt.sessionIds) }) }
-            })
-          ]);
-        } else {
-          await prisma.registrationOption.create({
-            data: {
-              id: uuidv4(),
-              registrationId: existingReg.id,
-              eventOptionId: opt.eventOptionId,
-              quantity: opt.quantity,
-              variantId: opt.variantId || null,
-              sessionId: opt.sessionId || null,
-              sessionIds: opt.sessionIds || [],
-              appliedTierId: opt.appliedTierId || null,
-              priceSnapshot: opt.priceSnapshot,
-              tranches: {
-                create: [{
-                  id: uuidv4(),
-                  quantity: opt.quantity,
-                  priceSnapshot: opt.priceSnapshot,
-                  appliedTierId: opt.appliedTierId || null,
-                }]
-              }
-            }
-          });
-        }
-      }
-      // Only downgrade from paid if the newly added items actually cost something
-      const newItemsCost = resolvedOptions.reduce((sum, opt) => {
-        return sum + ((opt.priceSnapshot || 0) * (opt.quantity || 0));
-      }, 0);
-      if (existingReg.status === 'paid' && newItemsCost > 0) {
-        await prisma.registration.update({ where: { id: existingReg.id }, data: { status: 'partial_paid', updatedAt: new Date() } });
-      } else {
-        await prisma.registration.update({ where: { id: existingReg.id }, data: { updatedAt: new Date() } });
-      }
-      registration = await prisma.registration.findUnique({
-        where: { id: existingReg.id },
-        include: {
-          registrationOptions: { include: { eventOption: true, tranches: true } },
-          event: true,
-          user: { select: { id: true, name: true, email: true, phoneNumber: true } }
-        }
-      });
-    } else {
-      isNewRegistration = true;
-      // Create new registration
-      const registrationId = uuidv4();
-      registration = await prisma.registration.create({
-        data: {
-          id: registrationId,
-          userId,
-          eventId,
-          updatedAt: new Date(),
-          registrationOptions: {
-            create: resolvedOptions.map(option => ({
-              id: uuidv4(),
-              eventOptionId: option.eventOptionId,
-              quantity: option.quantity,
-              variantId: option.variantId || null,
-              sessionId: option.sessionId || null,
-              sessionIds: option.sessionIds || [],
-              appliedTierId: option.appliedTierId || null,
-              priceSnapshot: option.priceSnapshot,
-              tranches: {
-                create: [{
-                  id: uuidv4(),
-                  quantity: option.quantity,
-                  priceSnapshot: option.priceSnapshot,
-                  appliedTierId: option.appliedTierId || null,
-                }]
-              }
-            }))
-          }
-        },
-        include: {
-          registrationOptions: { include: { eventOption: true, tranches: true } },
-          event: true,
-          user: { select: { id: true, name: true, email: true, phoneNumber: true } }
-        }
-      });
-    }
-
-    if (cleanAttendees.length > 0) {
-      await createAttendees(registration.id, cleanAttendees);
-      queueConsentRequests(registration.id);
-    }
-    if (waitlistOffer) {
-      await prisma.waitlistEntry.update({
-        where: { id: waitlistOffer.id },
-        data: { status: 'claimed', claimedAt: new Date(), registrationId: registration.id, offerTokenHash: null },
-      });
-    }
-    if (ticketDelivery) {
-      await prisma.registration.update({ where: { id: registration.id }, data: { ticketDelivery } });
-    }
-
-    // Bundle deals, then the coupon (or re-work an existing one over the merged items).
-    let couponError = null;
-    const hasDiscount = (await recalculateRegistrationDiscount(registration.id)) > 0;
-    if (couponCode) {
-      try {
-        await applyCouponToRegistration({ registrationId: registration.id, code: couponCode });
-      } catch (e) {
-        // Lost a race for the last use since the check above — keep the registration.
-        if (!e.isCouponError) throw e;
-        couponError = e.message;
-      }
-    }
-    if (couponCode || hasDiscount || !isNewRegistration || cleanAttendees.length > 0 || ticketDelivery) {
-      registration = await prisma.registration.findUnique({
-        where: { id: registration.id },
-        include: {
-          registrationOptions: { include: { eventOption: true, tranches: true } },
-          event: true,
-          user: { select: { id: true, name: true, email: true, phoneNumber: true } },
-          couponRedemptions: ACTIVE_COUPONS_INCLUDE,
-
-          bundleApplications: BUNDLE_APPS_INCLUDE,
-          attendees: ATTENDEES_INCLUDE,
-        }
-      });
-    }
-
-    // If total due is zero, mark as paid and generate/update tickets if no required form
-    let freeTicketMockReq = null, freeTicketMockRes = null;
-    try {
-      const totalDue = computeRegistrationTotalDue(registration, new Date());
-      if (totalDue === 0) {
-        // Mark paid (no-op if already paid)
-        if (registration.status !== 'paid') {
-          await prisma.registration.update({ where: { id: registration.id }, data: { status: 'paid', updatedAt: new Date() } });
-        }
-        // check if event has a required form
-        let hasRequiredForm = false;
-        try {
-          const form = await prisma.eventForm.findUnique({ where: { eventId: registration.eventId } });
-          hasRequiredForm = !!(form && form.isRequired);
-        } catch {}
-        if (!hasRequiredForm) {
-          // Same generator as paid registrations: a ticket per named attendee, and one
-          // shared quantity ticket for the rest of each line.
-          await generateTicketsForRegistration(registration.id);
-          // Capture for chained email — tickets sent after registration confirmation
-          freeTicketMockReq = { user: { id: registration.userId }, body: { registrationId: registration.id } };
-          freeTicketMockRes = { status: () => freeTicketMockRes, json: () => {} };
-        }
-
-        // reflect status change in the returned object
-        registration.status = 'paid';
-      }
-    } catch (e) {
-      // ignore errors in auto-generation path; manual generation remains available
-    }
-
-    // Fire-and-forget: registration email first, then tickets (guarantees order)
-    const { sendRegistrationEmails, sendRegistrationUpdatedEmails } = require('../utils/notifications');
-    const _regId = registration.id;
-    const _freeTicketReq = freeTicketMockReq;
-    const _freeTicketRes = freeTicketMockRes;
-    (async () => {
-      try {
-        if (isNewRegistration) {
-          await sendRegistrationEmails(_regId);
-        } else {
-          await sendRegistrationUpdatedEmails(_regId);
-        }
-      } catch (e) { console.error('Failed to send registration emails:', e); }
-      if (_freeTicketReq) {
-        try { await emailTickets(_freeTicketReq, _freeTicketRes); } catch (e) { console.error('Error emailing tickets for free registration:', e); }
-      }
-    })();
-
-    // Funnel: this registration came from a tracked (cookie-consented) visit.
-    if (analyticsSessionId) {
-      const { recordSubmit } = require('../utils/analytics');
-      recordSubmit(registration, analyticsSessionId).catch(e => console.warn('[analytics] submit not recorded:', e?.message || e));
-    }
-
-    res.status(201).json({ ...attachComputedTotals(registration), ...(couponError ? { couponError } : {}) });
+    const actor = req.user ? { id: req.user.id, role: req.user.role, email: req.user.email } : null;
+    const { registration, couponError } = await registrationService.createRegistration(req.body || {}, actor);
+    res.status(201).json({ ...registration, ...(couponError ? { couponError } : {}) });
   } catch (error) {
     res.status(400).json({ message: error.message });
   }
@@ -566,7 +68,13 @@ const getRegistrations = async (req, res) => {
     // array of every registration) working unchanged; callers that pass either param get back
     // the { data, total, page, limit, pages } shape used by /api/payments and /api/users.
     // Campus-scoped staff: registrations for events they can see.
-    const where = await require('../utils/campusScope').listWhere(req, 'event');
+    const scopeWhere = await require('../utils/campusScope').listWhere(req, 'event');
+    // Narrowing filters, so callers needn't download every registration ever made:
+    // ?unpaid=1 — still owing (not paid or cancelled); ?userId= — one person's.
+    const filters = [];
+    if (['1', 'true'].includes(String(req.query.unpaid || ''))) filters.push({ status: { in: ['pending', 'confirmed', 'partial_paid'] } });
+    if (req.query.userId) filters.push({ userId: String(req.query.userId) });
+    const where = filters.length ? { AND: [scopeWhere, ...filters] } : scopeWhere;
     if (typeof req.query.page === 'undefined' && typeof req.query.limit === 'undefined') {
       const registrations = await prisma.registration.findMany({ where, include });
       return res.json(attachComputedTotalsToList(registrations));
@@ -818,71 +326,7 @@ const updateRegistrationStatus = async (req, res) => {
 // @access  Private
 const cancelRegistration = async (req, res) => {
   try {
-    const registration = await prisma.registration.findUnique({
-      where: { id: req.params.id },
-      include: { event: { select: { endDate: true } } }
-    });
-
-    if (!registration) {
-      res.status(404);
-      throw new Error('Registration not found');
-    }
-
-    // Check if user is authorized to cancel this registration
-    if (registration.userId !== req.user.id && req.user.role !== 'admin') {
-      res.status(403);
-      throw new Error('Not authorized to cancel this registration');
-    }
-
-    // If event is in the past, block self-cancellation (mirrors the edit-block above)
-    if (req.user.role !== 'admin' && registration.event?.endDate && new Date(registration.event.endDate).getTime() < Date.now()) {
-      res.status(400);
-      throw new Error('This event has already ended; registration can no longer be cancelled');
-    }
-
-    await assertEventOpen(registration.eventId, res);
-
-    // Check if registration can be cancelled
-    if (registration.status === 'cancelled') {
-      res.status(400);
-      throw new Error('Registration is already cancelled');
-    }
-
-    // Non-admins cannot cancel a registration that has payments against it
-    if (req.user.role !== 'admin') {
-      const paymentCount = await prisma.payment.count({
-        where: { registrationId: registration.id, amount: { gt: 0 } }
-      });
-      if (paymentCount > 0) {
-        res.status(403);
-        throw new Error('This registration has payments recorded against it and cannot be self-cancelled. Please contact the organisation for assistance.');
-      }
-    }
-
-    const updatedRegistration = await prisma.registration.update({
-      where: { id: req.params.id },
-      data: {
-        status: 'cancelled',
-        updatedAt: new Date()
-      }
-    });
-    await releaseRegistrationCoupons(req.params.id);
-    queueWaitlist(registration.eventId);
-
-    // Only log when staff cancels on someone else's behalf — a routine self-service
-    // cancellation isn't an admin action worth cluttering the audit trail with.
-    if (registration.userId !== req.user.id) {
-      logAdminAction({
-        actorId: req.user.id,
-        actorRole: req.user.role,
-        action: 'registration_cancelled',
-        targetType: 'Registration',
-        targetId: req.params.id,
-        metadata: { registrationOwnerId: registration.userId },
-        ip: getClientIp(req),
-      });
-    }
-
+    const updatedRegistration = await registrationService.cancelRegistration(req.params.id, req.user, getClientIp(req));
     res.json({ message: 'Registration cancelled', registration: updatedRegistration });
   } catch (error) {
     res.status(400).json({ message: error.message });
@@ -1507,6 +951,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).
@@ -2132,7 +1588,6 @@ async function syncStatusAfterDiscount(registrationId) {
   return status;
 }
 
-const isStaffRole = (role) => ['admin', 'supervisor', 'staff'].includes(role);
 
 // @desc    Apply a coupon code to an existing registration
 // @route   POST /api/registrations/:id/coupon

backend/src/controllers/reportController.js

@@ -1,5 +1,6 @@
 const PDFDocument = require('pdfkit');
-const ExcelJS = require('exceljs');
+// ExcelTS: a maintained TypeScript port of exceljs (same API, no dependencies).
+const ExcelJS = require('@cj-tech-master/excelts');
 const fs = require('fs');
 const path = require('path');
 const { sendMail, emailWrapper } = require('../utils/email');

backend/src/controllers/seasonPassController.js

@@ -0,0 +1,146 @@
+const prisma = require('../config/db');
+const { logAdminAction } = require('../utils/adminAudit');
+const { getClientIp } = require('../utils/requestUtils');
+const { scopeFor, canManage } = require('../utils/campusScope');
+const passes = require('../utils/seasonPass');
+
+const fail = (res, error) => res.status(error.statusCode || 400).json({ message: error.message });
+
+const audit = (req, pass, action, metadata = {}) => logAdminAction({
+  actorId: req.user.id, actorRole: req.user.role, action: 'season_pass_changed', targetType: 'SeasonPass', targetId: pass.id,
+  metadata: { action, name: pass.name, ...metadata }, ip: getClientIp(req),
+});
+
+/** Campus-scoped supervisors may only put their own campuses' events on a pass. */
+async function assertCampuses(req, campusIds) {
+  const scope = await scopeFor(req);
+  if (scope && campusIds.some(c => !canManage(scope, c))) {
+    const err = new Error('You can only put events from your own campuses on a pass (not events for all campuses).');
+    err.statusCode = 403;
+    throw err;
+  }
+}
+
+const frontendUrl = () => String(process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');
+
+// @desc    A series' passes with their events, shares, and how many were sold
+// @route   GET /api/season-passes?seriesId=
+// @access  Private/Supervisor
+const listPasses = async (req, res) => {
+  try {
+    const where = req.query.seriesId ? { seriesId: String(req.query.seriesId) } : {};
+    const rows = await prisma.seasonPass.findMany({ where, orderBy: { createdAt: 'asc' }, include: passes.PASS_INCLUDE });
+    const sold = await prisma.seasonPassPurchase.groupBy({ by: ['passId', 'status'], where: { passId: { in: rows.map(r => r.id) } }, _sum: { quantity: true } });
+    res.json(rows.map(p => ({
+      ...passes.passView(p),
+      sold: sold.filter(s => s.passId === p.id && s.status === 'paid').reduce((n, s) => n + (s._sum.quantity || 0), 0),
+      unpaid: sold.filter(s => s.passId === p.id && s.status === 'pending').reduce((n, s) => n + (s._sum.quantity || 0), 0),
+    })));
+  } catch (error) { fail(res, error); }
+};
+
+// @route   POST /api/season-passes  { seriesId, name, description?, price, saleEndsAt?, items: [{ eventId, eventOptionId, variantId? }] }
+// @access  Private/Supervisor
+const createPass = async (req, res) => {
+  try {
+    const seriesId = String(req.body?.seriesId || '');
+    if (!(await prisma.eventSeries.findUnique({ where: { id: seriesId }, select: { id: true } }))) return res.status(404).json({ message: 'Series not found' });
+    const { data, items } = await passes.cleanPassInput(req.body, seriesId);
+    await assertCampuses(req, items.map(i => i.campusId));
+    const pass = await prisma.seasonPass.create({
+      data: { ...data, seriesId, items: { create: items.map(({ campusId, ...i }) => i) } },
+    });
+    audit(req, pass, 'created', { events: items.length, price: pass.price });
+    res.status(201).json(passes.passView(await passes.loadPass(pass.id)));
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    Change a pass. Its events can only change while nobody has bought it.
+// @route   PUT /api/season-passes/:id
+// @access  Private/Supervisor
+const updatePass = async (req, res) => {
+  try {
+    const current = await passes.loadPass(req.params.id);
+    await assertCampuses(req, current.items.map(i => i.event.campusId));
+    const { data, items } = await passes.cleanPassInput(req.body, current.seriesId, current);
+    const bought = await prisma.seasonPassPurchase.count({ where: { passId: current.id } });
+    if (bought > 0 && (items || (data.price !== undefined && data.price !== current.price))) {
+      return res.status(409).json({ message: 'People have bought this pass, so its events and price can\'t change. Switch it off and make a new one instead.' });
+    }
+    if (items) await assertCampuses(req, items.map(i => i.campusId));
+    await prisma.$transaction(async tx => {
+      await tx.seasonPass.update({ where: { id: current.id }, data });
+      if (items) {
+        await tx.seasonPassItem.deleteMany({ where: { passId: current.id } });
+        await tx.seasonPassItem.createMany({ data: items.map(({ campusId, ...i }) => ({ ...i, passId: current.id })) });
+      }
+    });
+    audit(req, current, 'updated', { changedKeys: [...Object.keys(data), ...(items ? ['items'] : [])] });
+    res.json(passes.passView(await passes.loadPass(current.id)));
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    Delete a pass nobody has bought (otherwise switch it off)
+// @route   DELETE /api/season-passes/:id
+// @access  Private/Supervisor
+const deletePass = async (req, res) => {
+  try {
+    const current = await passes.loadPass(req.params.id);
+    await assertCampuses(req, current.items.map(i => i.event.campusId));
+    if (await prisma.seasonPassPurchase.count({ where: { passId: current.id } })) {
+      return res.status(409).json({ message: 'People have bought this pass, so it can\'t be deleted — switch it off instead.' });
+    }
+    await prisma.seasonPass.delete({ where: { id: current.id } });
+    audit(req, current, 'deleted');
+    res.json({ ok: true });
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    Buy passes: registers the buyer at every event on it, then the checkout (or tickets, if free)
+// @route   POST /api/season-passes/:id/buy  { quantity, provider? }
+// @access  Private
+const buy = async (req, res) => {
+  try {
+    const pass = await prisma.seasonPass.findUnique({ where: { id: req.params.id }, select: { series: { select: { slug: true } } } });
+    if (!pass) return res.status(404).json({ message: 'Season pass not found' });
+    const back = `${frontendUrl()}/series/${pass.series.slug}`;
+    const result = await passes.buyPass(req.params.id, req.user.id, {
+      quantity: req.body?.quantity ?? 1, provider: req.body?.provider || null,
+      successUrl: `${back}?pass=paid`, cancelUrl: `${back}?pass=cancelled`, failureUrl: `${back}?pass=failed`,
+    });
+    res.status(201).json(result);
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    Pay what's still owed on a purchase (a new checkout)
+// @route   POST /api/season-passes/purchases/:id/checkout
+// @access  Private (the buyer)
+const payPurchase = async (req, res) => {
+  try {
+    const purchase = await prisma.seasonPassPurchase.findUnique({ where: { id: req.params.id }, select: { userId: true, pass: { select: { series: { select: { slug: true } } } } } });
+    if (!purchase || purchase.userId !== req.user.id) return res.status(404).json({ message: 'Purchase not found' });
+    const back = `${frontendUrl()}/series/${purchase.pass.series.slug}`;
+    res.json(await passes.startPassCheckout(req.params.id, req.user.id, {
+      provider: req.body?.provider || null, successUrl: `${back}?pass=paid`, cancelUrl: `${back}?pass=cancelled`, failureUrl: `${back}?pass=failed`,
+    }));
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    The signed-in person's pass purchases
+// @route   GET /api/season-passes/mine
+// @access  Private
+const myPurchases = async (req, res) => {
+  try {
+    const rows = await prisma.seasonPassPurchase.findMany({
+      where: { userId: req.user.id }, orderBy: { createdAt: 'desc' },
+      select: {
+        id: true, quantity: true, total: true, status: true, createdAt: true,
+        pass: { select: { id: true, name: true, series: { select: { name: true, slug: true } } } },
+        registrations: { select: { id: true, status: true, event: { select: { id: true, title: true, startDate: true } } } },
+      },
+    });
+    res.json(rows);
+  } catch (error) { fail(res, error); }
+};
+
+module.exports = { listPasses, createPass, updatePass, deletePass, buy, payPurchase, myPurchases };

backend/src/controllers/sectionController.js

@@ -1,189 +1,45 @@
-const prisma = require('../config/db');
-const { v4: uuidv4 } = require('uuid');
+// Scanning sections: which ticket types may come in at which door. Shared with
+// /api/v2/sections (services/setup.ts, 1.51.8).
+const setup = require('../services/setup');
+const { listWhere } = require('../utils/campusScope');
+
+const fail = (res, error) => res.status(error.statusCode || 400).json({ message: error.message });
 
-//
 // @desc    Get sections (optionally by event)
 // @route   GET /api/sections?eventId=xxx
 // @access  Private/Staff
-//
 const getSections = async (req, res) => {
-    try {
-        const { eventId } = req.query;
-
-        const { withScope, listWhere } = require('../utils/campusScope');
-        const where = withScope(eventId && eventId !== 'all' ? { eventId } : {}, await listWhere(req, 'event'));
-
-        const sections = await prisma.section.findMany({
-            where,
-            include: {
-                allowedOptions: {
-                    include: {
-                        eventOption: true
-                    }
-                },
-                event: {
-                    select: { id: true, title: true }
-                }
-            },
-            orderBy: { name: 'asc' }
-        });
-
-        res.json(sections);
-    } catch (error) {
-        res.status(400).json({ message: error.message });
-    }
+  try {
+    res.json(await setup.listSections(req.query.eventId, await listWhere(req, 'event')));
+  } catch (error) { fail(res, error); }
 };
 
-//
 // @desc    Create section
 // @route   POST /api/sections
 // @access  Private/Admin/Supervisor
-//
 const createSection = async (req, res) => {
-    try {
-        const { eventId, name, allowedOptionIds } = req.body;
-
-        if (!eventId || !name) {
-            res.status(400);
-            throw new Error('Event and section name are required');
-        }
-
-        const event = await prisma.event.findUnique({
-            where: { id: eventId }
-        });
-
-        if (!event) {
-            res.status(404);
-            throw new Error('Event not found');
-        }
-
-        const section = await prisma.section.create({
-            data: {
-                id: uuidv4(),
-                eventId,
-                name,
-                updatedAt: new Date()
-            }
-        });
-
-        // Attach allowed options if provided
-        if (Array.isArray(allowedOptionIds) && allowedOptionIds.length > 0) {
-            await prisma.sectionOption.createMany({
-                data: allowedOptionIds.map(optionId => ({
-                    id: uuidv4(),
-                    sectionId: section.id,
-                    eventOptionId: optionId
-                })),
-                skipDuplicates: true
-            });
-        }
-
-        const fullSection = await prisma.section.findUnique({
-            where: { id: section.id },
-            include: {
-                allowedOptions: {
-                    include: { eventOption: true }
-                }
-            }
-        });
-
-        res.status(201).json(fullSection);
-
-    } catch (error) {
-        res.status(400).json({ message: error.message });
-    }
+  try {
+    res.status(201).json(await setup.createSection(req.body || {}));
+  } catch (error) { fail(res, error); }
 };
 
-//
 // @desc    Update section
 // @route   PUT /api/sections/:id
 // @access  Private/Admin/Supervisor
-//
 const updateSection = async (req, res) => {
-    try {
-        const { name, allowedOptionIds } = req.body;
-
-        const section = await prisma.section.findUnique({
-            where: { id: req.params.id }
-        });
-
-        if (!section) {
-            res.status(404);
-            throw new Error('Section not found');
-        }
-
-        const updatedSection = await prisma.section.update({
-            where: { id: req.params.id },
-            data: {
-                name: name || section.name,
-                updatedAt: new Date()
-            }
-        });
-
-        // If allowed options supplied → reset them
-        if (Array.isArray(allowedOptionIds)) {
-
-            await prisma.sectionOption.deleteMany({
-                where: { sectionId: section.id }
-            });
-
-            if (allowedOptionIds.length > 0) {
-                await prisma.sectionOption.createMany({
-                    data: allowedOptionIds.map(optionId => ({
-                        id: uuidv4(),
-                        sectionId: section.id,
-                        eventOptionId: optionId
-                    }))
-                });
-            }
-        }
-
-        const fullSection = await prisma.section.findUnique({
-            where: { id: section.id },
-            include: {
-                allowedOptions: {
-                    include: { eventOption: true }
-                }
-            }
-        });
-
-        res.json(fullSection);
-
-    } catch (error) {
-        res.status(400).json({ message: error.message });
-    }
+  try {
+    res.json(await setup.updateSection(req.params.id, req.body || {}));
+  } catch (error) { fail(res, error); }
 };
 
-//
 // @desc    Delete section
 // @route   DELETE /api/sections/:id
 // @access  Private/Admin
-//
 const deleteSection = async (req, res) => {
-    try {
-        const section = await prisma.section.findUnique({
-            where: { id: req.params.id }
-        });
-
-        if (!section) {
-            res.status(404);
-            throw new Error('Section not found');
-        }
-
-        await prisma.section.delete({
-            where: { id: section.id }
-        });
-
-        res.json({ message: 'Section deleted' });
-
-    } catch (error) {
-        res.status(400).json({ message: error.message });
-    }
+  try {
+    await setup.deleteSection(req.params.id);
+    res.json({ message: 'Section deleted' });
+  } catch (error) { fail(res, error); }
 };
 
-module.exports = {
-    getSections,
-    createSection,
-    updateSection,
-    deleteSection
-};
+module.exports = { getSections, createSection, updateSection, deleteSection };

backend/src/controllers/seriesController.js

@@ -0,0 +1,126 @@
+const prisma = require('../config/db');
+const { logAdminAction } = require('../utils/adminAudit');
+const { getClientIp } = require('../utils/requestUtils');
+const { cleanSeriesInput, publicEventWhere, splitEvents, follow, unfollow, compareSeries } = require('../utils/series');
+const { scopeFor, canView, eventWhere } = require('../utils/campusScope');
+const { EVENT_CAMPUS_SELECT } = require('../utils/campuses');
+
+const fail = (res, error) => res.status(error.statusCode || (error.code === 'P2002' ? 409 : 400)).json({
+  message: error.code === 'P2002' ? 'Another series already uses that web address' : error.message,
+});
+
+const audit = (req, action, series, metadata = {}) => logAdminAction({
+  actorId: req.user.id, actorRole: req.user.role, action, targetType: 'EventSeries', targetId: series.id,
+  metadata: { name: series.name, ...metadata }, ip: getClientIp(req),
+});
+
+// @desc    Every series, with its events (the ones this person may see) and number of followers
+// @route   GET /api/series
+// @access  Private/Supervisor
+const listSeries = async (req, res) => {
+  try {
+    const scope = await scopeFor(req);
+    const rows = await prisma.eventSeries.findMany({
+      orderBy: { name: 'asc' },
+      include: {
+        events: { orderBy: { startDate: 'desc' }, select: { id: true, title: true, startDate: true, endDate: true, isActive: true, isHidden: true, campusId: true, campus: { select: EVENT_CAMPUS_SELECT } } },
+        _count: { select: { followers: true, events: true } },
+      },
+    });
+    // A series spans campuses; campus-scoped staff see the series, but only their campuses' events in it.
+    res.json(rows.map(({ _count, events, ...s }) => ({
+      ...s,
+      followers: _count.followers,
+      eventCount: _count.events,
+      events: events.filter(e => canView(scope, e.campusId)),
+    })));
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    Create a series
+// @route   POST /api/series
+// @access  Private/Supervisor
+const createSeries = async (req, res) => {
+  try {
+    const series = await prisma.eventSeries.create({ data: cleanSeriesInput(req.body) });
+    audit(req, 'series_created', series);
+    res.status(201).json(series);
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    Rename a series or change its page
+// @route   PUT /api/series/:id
+// @access  Private/Supervisor
+const updateSeries = async (req, res) => {
+  try {
+    const current = await prisma.eventSeries.findUnique({ where: { id: req.params.id } });
+    if (!current) return res.status(404).json({ message: 'Series not found' });
+    const data = cleanSeriesInput(req.body, current);
+    const series = await prisma.eventSeries.update({ where: { id: current.id }, data });
+    audit(req, 'series_updated', series, { changedKeys: Object.keys(data) });
+    res.json(series);
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    Delete a series (its events stay, just without a series; followers are dropped)
+// @route   DELETE /api/series/:id
+// @access  Private/Admin
+const deleteSeries = async (req, res) => {
+  try {
+    const current = await prisma.eventSeries.findUnique({ where: { id: req.params.id }, include: { _count: { select: { events: true, followers: true } } } });
+    if (!current) return res.status(404).json({ message: 'Series not found' });
+    if (await prisma.seasonPassPurchase.count({ where: { pass: { seriesId: current.id } } })) {
+      return res.status(409).json({ message: 'People have bought season passes for this series, so it can\'t be deleted.' });
+    }
+    await prisma.eventSeries.delete({ where: { id: current.id } });
+    audit(req, 'series_deleted', current, { events: current._count.events, followers: current._count.followers });
+    res.json({ ok: true });
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    A series' public page: its details, upcoming and past public events, and whether the
+//          signed-in person follows it
+// @route   GET /api/series/by-slug/:slug
+// @access  Public
+const getSeriesBySlug = async (req, res) => {
+  try {
+    const series = await prisma.eventSeries.findUnique({
+      where: { slug: String(req.params.slug) },
+      select: { id: true, name: true, slug: true, description: true, picture: true },
+    });
+    if (!series) return res.status(404).json({ message: 'Series not found' });
+    const events = await prisma.event.findMany({
+      where: { ...publicEventWhere(), seriesId: series.id },
+      select: { id: true, title: true, startDate: true, endDate: true, location: true, campus: { select: EVENT_CAMPUS_SELECT } },
+    });
+    const { upcoming, past } = splitEvents(events);
+    const following = req.user ? !!(await prisma.seriesFollow.findUnique({ where: { seriesId_userId: { seriesId: series.id, userId: req.user.id } } })) : false;
+    // Season passes switched on (1.47.3); `unavailable` says why one can't be bought now.
+    const { passView, PASS_INCLUDE } = require('../utils/seasonPass');
+    const passes = (await prisma.seasonPass.findMany({ where: { seriesId: series.id, isActive: true }, orderBy: { createdAt: 'asc' }, include: PASS_INCLUDE }))
+      .map(p => passView(p))
+      .map(({ items, ...p }) => ({ ...p, items: items.map(({ campusId, ...i }) => i) }));
+    res.json({ ...series, upcoming, past, following, passes });
+  } catch (error) { fail(res, error); }
+};
+
+// @desc    Year-on-year: registrations, tickets, income and attendance per event in the series
+//          (the events this person may see), oldest first, with the change from the one before
+// @route   GET /api/series/:id/compare
+// @access  Private/Supervisor
+const compare = async (req, res) => {
+  try {
+    res.json(await compareSeries(req.params.id, { scopeWhere: eventWhere(await scopeFor(req)) }));
+  } catch (error) { fail(res, error); }
+};
+
+// @route   POST /api/series/:id/follow · DELETE /api/series/:id/follow
+// @access  Private
+const followSeries = async (req, res) => {
+  try { await follow(req.params.id, req.user.id); res.json({ following: true }); } catch (error) { fail(res, error); }
+};
+const unfollowSeries = async (req, res) => {
+  try { await unfollow(req.params.id, req.user.id); res.json({ following: false }); } catch (error) { fail(res, error); }
+};
+
+module.exports = { listSeries, createSeries, updateSeries, deleteSeries, getSeriesBySlug, followSeries, unfollowSeries, compare };

backend/src/controllers/ticketController.js

@@ -1,8 +1,9 @@
 const prisma = require('../config/db');
-const { v4: uuidv4 } = require('uuid');
 const { safeErrorMessage } = require('../utils/errorUtils');
 const { generateTicketsForRegistration } = require('../utils/ticketUtils');
 const { assertRegistrationEventOpen } = require('../utils/cashupUtils');
+// Scanning, shared with /api/v2/checkin (TypeScript, 1.51.2).
+const checkin = require('../services/checkin');
 
 // @desc    Generate tickets for a registration
 // @route   POST /api/tickets/generate
@@ -256,99 +257,11 @@ const getTicketByQrCode = async (req, res) => {
 // @access  Private/Staff
 const getScanPreview = async (req, res) => {
   try {
-    // Single JOIN query instead of 6 sequential Prisma round-trips (critical for remote DBs)
-    const rows = await prisma.$queryRaw`
-      SELECT
-        t.id,
-        t."qrCode",
-        t.quantity,
-        t."isUsed",
-        t."eventId",
-        ro.id                AS "registrationOptionId",
-        ro."sessionId"       AS "pinnedSessionId",
-        ro."sessionIds"      AS "chosenSessionIds",
-        eo.id                AS "eventOptionId",
-        eo.name              AS "eventOptionName",
-        ov.id                AS "variantId",
-        ov.name              AS "variantName",
-        e.id                 AS "evId",
-        e.title              AS "eventTitle",
-        e."scheduleType"     AS "scheduleType",
-        u.id                 AS "userId",
-        u.name               AS "userName",
-        a.name               AS "attendeeName",
-        COALESCE(
-          json_agg(
-            json_build_object(
-              'quantityRedeemed', tu."quantityRedeemed",
-              'scannedAt',        tu."scannedAt",
-              'sessionId',        tu."sessionId"
-            )
-          ) FILTER (WHERE tu.id IS NOT NULL),
-          '[]'::json
-        ) AS usages
-      FROM "Ticket" t
-      LEFT JOIN "RegistrationOption" ro ON ro.id = t."registrationOptionId"
-      LEFT JOIN "EventOption"        eo ON eo.id = ro."eventOptionId"
-      LEFT JOIN "OptionVariant"      ov ON ov.id = ro."variantId"
-      LEFT JOIN "Event"               e ON  e.id = t."eventId"
-      LEFT JOIN "User"                u ON  u.id = t."userId"
-      LEFT JOIN "Attendee"            a ON  a.id = t."attendeeId"
-      LEFT JOIN "TicketUsage"        tu ON tu."ticketId" = t.id
-      WHERE t."qrCode" = ${req.params.qrCode}
-      GROUP BY t.id, ro.id, eo.id, ov.id, e.id, u.id, a.id
-    `;
-
-    if (!rows || rows.length === 0) {
-      const { findTransferByOldCode, transferredMessage } = require('../utils/ticketTransfer');
-      const transfer = await findTransferByOldCode(req.params.qrCode);
-      if (transfer) return res.status(410).json({ message: transferredMessage(transfer), code: 'TICKET_TRANSFERRED' });
-      res.status(404);
-      throw new Error('Ticket not found');
-    }
-
-    const r = rows[0];
-    const { consentStatusForTickets } = require('../utils/consent');
-    const consentStatus = (await consentStatusForTickets([r.id])).get(r.id) || 'not_required';
-    const usages = r.usages || [];
-    // Multi-day events: check-in is per session, so what's left is counted for the
-    // session this scan is for (the one picked, or today's).
-    let remaining = Number(r.quantity) - usages.reduce((s, u) => s + (u.quantityRedeemed || 1), 0);
-    let session = null;
-    let sessionError = null;
-    if (r.scheduleType === 'sessions') {
-      const sessionsUtil = require('../utils/sessions');
-      const schedule = await sessionsUtil.eventSchedule(r.eventId);
-      const found = sessionsUtil.ticketScanSession(schedule, schedule.sessions, r.pinnedSessionId, req.query.sessionId || null, new Date(), r.chosenSessionIds);
-      sessionError = found.error;
-      if (found.session) {
-        session = { id: found.session.id, label: sessionsUtil.sessionLabel(found.session, schedule.sessions) };
-        remaining = Number(r.quantity) - sessionsUtil.redeemedForSession(usages, found.session.id);
-      } else {
-        remaining = 0;
-      }
-    }
-    res.json({
-      id:       r.id,
-      quantity: Number(r.quantity),
-      isUsed:   r.isUsed,
-      eventId:  r.eventId,
-      consentStatus,
-      remaining,
-      session,
-      sessionError,
-      registrationOption: {
-        id: r.registrationOptionId,
-        eventOption: { id: r.eventOptionId, name: r.eventOptionName },
-        variant: r.variantId ? { id: r.variantId, name: r.variantName } : null,
-      },
-      event:  { id: r.evId,   title: r.eventTitle },
-      user:   { id: r.userId, name:  r.userName   },
-      attendee: r.attendeeName ? { name: r.attendeeName } : null,
-      usages
-    });
+    const result = await checkin.previewScan(req.params.qrCode, { sessionId: req.query.sessionId || null });
+    if (result.outcome === 'transferred') return res.status(410).json({ message: result.message, code: 'TICKET_TRANSFERRED' });
+    res.json(result.ticket);
   } catch (error) {
-    res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(error) });
+    res.status(error.statusCode || (res.statusCode === 200 ? 400 : res.statusCode)).json({ message: safeErrorMessage(error) });
   }
 };
 
@@ -357,187 +270,19 @@ const getScanPreview = async (req, res) => {
 // @access  Private/Staff
 const scanTicket = async (req, res) => {
   try {
-    // Single JOIN query — avoids multiple sequential round-trips to the remote DB
-    const rows = await prisma.$queryRaw`
-      SELECT
-        t.id,
-        t.quantity,
-        t."isUsed",
-        t."eventId",
-        e.title              AS "eventTitle",
-        e."scheduleType"     AS "scheduleType",
-        ro."sessionId"       AS "pinnedSessionId",
-        ro."sessionIds"      AS "chosenSessionIds",
-        eo.id                AS "eventOptionId",
-        eo.name              AS "eventOptionName",
-        eo."isMainTicket"    AS "isMainTicket",
-        COALESCE(
-          json_agg(
-            json_build_object(
-              'id',               tu.id,
-              'quantityRedeemed', tu."quantityRedeemed",
-              'scannedAt',        tu."scannedAt",
-              'sessionId',        tu."sessionId"
-            )
-          ) FILTER (WHERE tu.id IS NOT NULL),
-          '[]'::json
-        ) AS usages
-      FROM "Ticket" t
-      LEFT JOIN "Event"              e  ON  e.id = t."eventId"
-      LEFT JOIN "RegistrationOption" ro ON ro.id = t."registrationOptionId"
-      LEFT JOIN "EventOption"        eo ON eo.id = ro."eventOptionId"
-      LEFT JOIN "TicketUsage"        tu ON tu."ticketId" = t.id
-      WHERE t."qrCode" = ${req.params.qrCode}
-      GROUP BY t.id, e.id, eo.id, ro.id
-    `;
-
-    if (!rows || rows.length === 0) {
-      const { findTransferByOldCode, transferredMessage } = require('../utils/ticketTransfer');
-      const transfer = await findTransferByOldCode(req.params.qrCode);
-      if (transfer) return res.status(410).json({ message: transferredMessage(transfer), code: 'TICKET_TRANSFERRED' });
-      res.status(404);
-      throw new Error('Ticket not found');
-    }
-
-    const r = rows[0];
-    const ticket = {
-      id:       r.id,
-      quantity: Number(r.quantity),
-      isUsed:   r.isUsed,
-      eventId:  r.eventId,
-      event:    { title: r.eventTitle },
-      registrationOption: { eventOption: { id: r.eventOptionId, name: r.eventOptionName, isMainTicket: r.isMainTicket } },
-      usages:   r.usages || []
-    };
-
-    // Optional server-side guard: ensure ticket belongs to the requested event when provided
-    const providedEventId = String((req.query?.eventId || req.body?.eventId) || '').trim();
-    if (providedEventId && ticket.eventId !== providedEventId) {
-      return res.status(400).json({ message: 'Ticket belongs to a different event', ticket });
-    }
-
-    // Section checks used to happen only in the browser; enforce them here too.
-    const sectionId = String((req.query?.sectionId || req.body?.sectionId) || '').trim() || null;
-    if (sectionId) {
-      const section = await prisma.section.findUnique({ where: { id: sectionId }, include: { allowedOptions: true } });
-      if (!section || section.eventId !== ticket.eventId) {
-        return res.status(400).json({ message: 'Section not found for this event', ticket });
-      }
-      if (!section.allowedOptions.some(o => o.eventOptionId === r.eventOptionId)) {
-        return res.status(400).json({ message: 'This ticket is not valid for this section', ticket });
-      }
-    }
-
-    // A section (or the whole event) locked to another device for offline scanning
-    // can't be scanned online — those scans would be invisible to the offline device.
-    const { blockingLock } = require('../utils/scanLocks');
-    const lock = await blockingLock({ eventId: ticket.eventId, optionId: r.eventOptionId }, { sectionId, deviceId: req.body?.deviceId || null });
-    if (lock) {
-      const scope = lock.section ? `"${lock.section.name}"` : 'This event';
-      return res.status(423).json({ message: `${scope} is offline-locked by ${lock.user?.name || 'another device'}${lock.deviceName ? ` on ${lock.deviceName}` : ''}. Scan it on that device, or ask a supervisor to release the lock.`, code: 'SCAN_LOCKED' });
-    }
-
-    // Multi-day events: the check-in is for one session (the one picked, or today's), and
-    // what's left is counted per session.
-    let session = null;
-    let sessionsUtil = null;
-    let schedule = null;
-    if (r.scheduleType === 'sessions') {
-      sessionsUtil = require('../utils/sessions');
-      schedule = await sessionsUtil.eventSchedule(ticket.eventId);
-      const found = sessionsUtil.ticketScanSession(schedule, schedule.sessions, r.pinnedSessionId, String(req.body?.sessionId || req.query?.sessionId || '').trim() || null, new Date(), r.chosenSessionIds);
-      if (!found.session) return res.status(400).json({ message: found.error, code: 'NO_SESSION', ticket });
-      session = found.session;
-    }
-
-    // Compute how many have already been redeemed
-    const totalRedeemed = session
-      ? sessionsUtil.redeemedForSession(ticket.usages, session.id)
-      : (ticket.usages || []).reduce((s, u) => s + (u.quantityRedeemed || 1), 0);
-    const remaining = (ticket.quantity || 1) - totalRedeemed;
-
-    if (remaining <= 0) {
-      if (session) {
-        const last = (ticket.usages || []).filter(u => u.sessionId === session.id).sort((a, b) => new Date(b.scannedAt) - new Date(a.scannedAt))[0];
-        const at = last ? new Date(last.scannedAt).toLocaleTimeString('en-ZA', { timeZone: sessionsUtil.TIMEZONE, hour: '2-digit', minute: '2-digit' }) : '';
-        return res.status(403).json({
-          message: `Already checked in for ${sessionsUtil.sessionLabel(session, schedule.sessions)}${at ? ` at ${at}` : ''}`,
-          ticket,
-          remaining: 0
-        });
-      }
-      return res.status(403).json({
-        message: 'Ticket has already been fully used',
-        ticket,
-        remaining: 0
-      });
-    }
-
-    // Youth events: no check-in without parental consent, unless a supervisor overrides.
-    const { consentStatusForTickets } = require('../utils/consent');
-    const consentStatus = (await consentStatusForTickets([ticket.id])).get(ticket.id) || 'not_required';
-    if (!['not_required', 'given'].includes(consentStatus)) {
-      const canOverride = ['admin', 'supervisor'].includes(req.user?.role);
-      if (!(req.body?.overrideConsent === true && canOverride)) {
-        const why = consentStatus === 'declined' ? 'Parental consent was declined' : consentStatus === 'pending' ? 'Parental consent is still pending' : 'Parental consent is missing';
-        return res.status(403).json({ message: `${why} — this ticket can't be checked in.`, code: 'CONSENT_REQUIRED', consentStatus, canOverride, ticket });
-      }
-      const { logAdminAction } = require('../utils/adminAudit');
-      const { getClientIp } = require('../utils/requestUtils');
-      logAdminAction({
-        actorId: req.user.id, actorRole: req.user.role, action: 'consent_override',
-        targetType: 'Ticket', targetId: ticket.id,
-        metadata: { consentStatus, eventId: ticket.eventId },
-        ip: getClientIp(req),
-      });
-    }
-
-    // Determine how many to redeem this scan (defaults to all remaining)
-    const requestedQty = parseInt(req.body?.qty || req.body?.quantity) || remaining;
-    const qtyToRedeem = Math.min(Math.max(1, requestedQty), remaining);
-
-    const newTotalRedeemed = totalRedeemed + qtyToRedeem;
-    const newRemaining = (ticket.quantity || 1) - newTotalRedeemed;
-    const fullyUsed = newRemaining <= 0;
-
-    // Run the usage insert and ticket status update in parallel — they don't depend on each other
-    const [ticketUsage] = await Promise.all([
-      prisma.ticketUsage.create({
-        data: {
-          id: uuidv4(),
-          ticketId: ticket.id,
-          scannedById: req.user.id,
-          quantityRedeemed: qtyToRedeem,
-          sessionId: session ? session.id : null,
-        }
-      }),
-      // A multi-session ticket is never "used up" — it's checked in again next session.
-      prisma.ticket.update({
-        where: { id: ticket.id },
-        data: { isUsed: session ? false : fullyUsed, updatedAt: new Date() }
-      })
-    ]);
-
-    // Only Main Tickets trigger a check-in notification (add-on tickets scanned via
-    // the QR camera flow are unaffected)
-    if (ticket.registrationOption?.eventOption?.isMainTicket) {
-      require('../utils/notifications')
-        .sendCheckInEmails(ticket.id, qtyToRedeem, newTotalRedeemed, newRemaining)
-        .catch(e => console.error('Failed to send check-in notification:', e));
-    }
-
-    const sessionPart = session ? ` for ${sessionsUtil.sessionLabel(session, schedule.sessions)}` : '';
-    res.json({
-      message: `Ticket scanned successfully${sessionPart} (${qtyToRedeem} of ${ticket.quantity || 1} redeemed${newRemaining > 0 ? `, ${newRemaining} remaining` : ''})`,
-      session: session ? { id: session.id, label: sessionsUtil.sessionLabel(session, schedule.sessions) } : null,
-      ticketUsage,
-      ticket,
-      qtyRedeemed: qtyToRedeem,
-      totalRedeemed: newTotalRedeemed,
-      remaining: newRemaining,
-    });
+    const { getClientIp } = require('../utils/requestUtils');
+    const result = await checkin.scanTicket(req.params.qrCode, req.user, {
+      eventId: req.query?.eventId || req.body?.eventId || null,
+      sectionId: req.query?.sectionId || req.body?.sectionId || null,
+      sessionId: req.body?.sessionId || req.query?.sessionId || null,
+      deviceId: req.body?.deviceId || null,
+      qty: parseInt(req.body?.qty || req.body?.quantity) || null,
+      overrideConsent: req.body?.overrideConsent === true,
+    }, getClientIp(req));
+    const { status, body } = checkin.v1ScanResponse(result);
+    res.status(status).json(body);
   } catch (error) {
-    res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(error) });
+    res.status(error.statusCode || (res.statusCode === 200 ? 400 : res.statusCode)).json({ message: safeErrorMessage(error) });
   }
 };
 

backend/src/controllers/userController.js

@@ -3,28 +3,22 @@ const { generateToken, hashPassword, comparePassword } = require('../config/auth
 const { v4: uuidv4 } = require('uuid');
 const { safeErrorMessage } = require('../utils/errorUtils');
 const { logSecurityEvent, getRecentSecurityEvents } = require('../utils/securityEvents');
-const { getSettingSync } = require('../utils/settingsCache');
 const {
   METHODS: TWO_FACTOR_METHODS,
   availableMethods,
   createChallenge,
   verifyChallenge,
   resendChallenge,
-  issueTrustedDevice,
-  isTrustedDevice,
   clearTrustedDevices,
   requiresTwoFactor,
-  enforcementMethod,
 } = require('../utils/twoFactor');
-const axios = require('axios');
 
 // ─── Helpers ────────────────────────────────────────────────────────────────
 
-// Org name for email subjects — falls back to Cross Code (the platform vendor)
-// rather than any specific customer's name when unconfigured.
-function getOrgName() {
-  return getSettingSync('org_name', process.env.ORG_NAME || 'Cross Code');
-}
+// Sign up, log in and profile changes are shared with /api/v2 (TypeScript, 1.51.2).
+const accounts = require('../services/auth');
+const { getOrgName, sendActivationLink, sendWelcomeEmail } = accounts;
+const { v1StatusOf } = require('../services/errors');
 
 // Resolve a client IP from the request (works behind proxies)
 function getClientIp(req) {
@@ -33,145 +27,10 @@ function getClientIp(req) {
   return req.socket?.remoteAddress || 'unknown';
 }
 
-const PRIVATE_IP_RE = /^(::1|::ffff:127\.|127\.|10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/;
-
-// Fire-and-forget: create a 24h activation token and deliver it to an inactive
-// account — via email if it has a real (non-guest) address, otherwise via
-// WhatsApp if it has a phone number. Used both when a login attempt hits an
-// inactive account, and immediately when an admin/supervisor creates an
-// account on someone's behalf (walk-in / manual registration).
-async function sendActivationLink(user) {
-  const hasRealEmail = !!(user?.email && !user.email.endsWith('@guest.local'));
-  if (!hasRealEmail && !user?.phoneNumber) return;
-  try {
-    const token = uuidv4();
-    const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000); // 24h
-    await prisma.passwordReset.updateMany({
-      where: { userId: user.id, used: false },
-      data: { used: true }
-    });
-    await prisma.passwordReset.create({
-      data: { id: uuidv4(), userId: user.id, token, expiresAt, used: false }
-    });
-    const baseUrl = process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001';
-    const activationUrl = `${baseUrl.replace(/\/$/, '')}/activate-account?token=${encodeURIComponent(token)}`;
-
-    if (hasRealEmail) {
-      const { sendMail, buildAccountActivationEmail } = require('../utils/email');
-      const content = buildAccountActivationEmail({ name: user.name, activationUrl });
-      sendMail({ to: user.email, subject: `Activate your ${getOrgName()} account`, ...content })
-        .catch(e => console.warn('[activation email] Failed:', e?.message || e));
-    } else {
-      const orgName = getOrgName();
-      const waMessage = [
-        `🔓 *Activate your ${orgName} account*`,
-        '',
-        `Hi ${user.name || 'there'},`,
-        '',
-        `Your account needs to be activated before you can log in. Tap the link below to set a password and activate your account:`,
-        '',
-        activationUrl,
-        '',
-        `_This link expires in 24 hours._`,
-      ].join('\n');
-      const { waTextAny } = require('../utils/notify');
-      waTextAny(user, waMessage).catch(e => console.warn('[activation WA] Failed:', e?.message || e));
-    }
-  } catch (e) {
-    console.warn('[activation token] Failed to create activation token:', e?.message || e);
-  }
-}
-
-// Fire-and-forget: send a login notification email with approximate geo location
-async function sendLoginNotification(user, req) {
-  try {
-    const ip = getClientIp(req);
-    const userAgent = req.headers['user-agent'] || 'Unknown device';
-    const when = new Date().toLocaleString('en-ZA', { timeZone: 'Africa/Johannesburg' });
-
-    let location = 'Unknown location';
-    if (ip !== 'unknown' && !PRIVATE_IP_RE.test(ip)) {
-      try {
-        const geo = await axios.get(
-          `http://ip-api.com/json/${ip}?fields=status,city,regionName,country`,
-          { timeout: 3000 }
-        );
-        if (geo.data?.status === 'success') {
-          const parts = [geo.data.city, geo.data.regionName, geo.data.country].filter(Boolean);
-          if (parts.length) location = parts.join(', ');
-        }
-      } catch { /* geo lookup failure is non-fatal */ }
-    }
-
-    const { sendMail, buildLoginNotificationEmail } = require('../utils/email');
-    const { buildWALogin } = require('../utils/waMessages');
-    const content = buildLoginNotificationEmail({ name: user.name, when, location, userAgent });
-    // Security: always email; also WhatsApp if preferred
-    await sendMail({ to: user.email, subject: `New login to your ${getOrgName()} account`, ...content });
-    const { waText } = require('../utils/notify');
-    await waText(user, buildWALogin({ name: user.name, when, location, userAgent })).catch(() => {});
-  } catch (e) {
-    console.warn('[login notification] Failed:', e?.message || e);
-  }
-}
-
-// Fire-and-forget: send welcome email with next upcoming events
-async function sendWelcomeEmail(user) {
-  try {
-    const events = await prisma.event.findMany({
-      where: { isActive: true, startDate: { gt: new Date() } },
-      orderBy: { startDate: 'asc' },
-      take: 3,
-      select: { title: true, startDate: true },
-    });
-    const { sendMail, buildWelcomeEmail } = require('../utils/email');
-    const { buildWAWelcome } = require('../utils/waMessages');
-    const content = buildWelcomeEmail({ name: user.name, events });
-    const { shouldEmail, waText } = require('../utils/notify');
-    // Welcome is always sent via email; also via WhatsApp if preferred
-    await sendMail({ to: user.email, subject: `Welcome to ${getOrgName()}!`, ...content });
-    await waText(user, buildWAWelcome({ name: user.name, events })).catch(() => {});
-  } catch (e) {
-    console.warn('[welcome email] Failed:', e?.message || e);
-  }
-}
-
-// Fields the login flow needs once the password (and any 2FA code) has checked out.
-const LOGIN_USER_SELECT = {
-  id: true, name: true, email: true, role: true, tokenVersion: true, isActive: true,
-  phoneNumber: true, notificationPreference: true, twoFactorEnabled: true, twoFactorMethod: true, newsAskedAt: true,
-  noticeVersionAccepted: true,
-};
-
-// Errors from utils/twoFactor carry their own HTTP status; everything else follows
-// the controller convention of res.status(...) before throwing.
+// Errors from utils/twoFactor and the services carry their own HTTP status; everything else
+// follows the controller convention of res.status(...) before throwing.
 function errorStatus(error, res) {
-  return error?.statusCode || (res.statusCode === 200 ? 400 : res.statusCode);
-}
-
-// Final step of a successful login (after the password, and the 2FA code when
-// required): notify, record the activity, and issue the session token.
-async function completeLogin(user, req, res, extra = {}) {
-  const noticePromptPending = await require('../utils/privacyNotice').noticePromptPending(user).catch(() => false);
-  // Retention: logging in keeps the account (and cancels an inactivity warning).
-  prisma.user.update({ where: { id: user.id }, data: { lastLoginAt: new Date(), inactivityWarnedAt: null } }).catch(() => {});
-
-  // Send login notification in the background
-  sendLoginNotification(user, req).catch(() => {});
-  logSecurityEvent({ userId: user.id, type: 'login', ip: getClientIp(req), userAgent: req.headers['user-agent'] }).catch(() => {});
-
-  res.json({
-    id: user.id,
-    name: user.name,
-    email: user.email,
-    role: user.role,
-    token: generateToken(user.id, user.role, user.tokenVersion),
-    // POPIA: ask about News & announcements once (see NewsPrompt on the frontend), and to
-    // accept a privacy notice version marked as a significant change (NoticePrompt).
-    newsPromptPending: !user.newsAskedAt,
-    noticePromptPending,
-    ...extra
-  });
+  return v1StatusOf(error, res.statusCode === 200 ? 400 : res.statusCode);
 }
 
 // @desc    Register a new user
@@ -179,79 +38,9 @@ async function completeLogin(user, req, res, extra = {}) {
 // @access  Public
 const registerUser = async (req, res) => {
   try {
-    const { name, email, password, phoneNumber, notificationPreference, newsOptIn } = req.body;
-
-    // Normalize phone using SA-aware normalisation
-    const { normalizeZAPhone, isValidZAPhone } = require('../utils/whatsapp');
-    const phone = normalizeZAPhone(phoneNumber) || (phoneNumber ? phoneNumber.replace(/\D/g, '') || null : null);
-
-    // Validate preference — WhatsApp requires a valid phone number
-    const allowedPrefs = ['email', 'whatsapp', 'both'];
-    let pref = allowedPrefs.includes(notificationPreference) ? notificationPreference : 'email';
-    if ((pref === 'whatsapp' || pref === 'both') && !isValidZAPhone(phoneNumber)) {
-      pref = 'email'; // silently fall back if no valid number
-    }
-
-    // Check if user already exists
-    const userExists = await prisma.user.findFirst({
-      where: {
-        OR: [
-          { email },
-          ...(phone ? [{ phoneNumber: phone }] : [])
-        ]
-      }
-    });
-
-    if (userExists) {
-      res.status(400);
-      throw new Error('User already exists');
-    }
-
-    // Hash password
-    const hashedPassword = await hashPassword(password);
-
-    // Create user
-    const user = await prisma.user.create({
-      data: {
-        id: uuidv4(),
-        name,
-        email,
-        password: hashedPassword,
-        phoneNumber: phone,
-        notificationPreference: pref,
-        updatedAt: new Date()
-      }
-    });
-
-    if (user) {
-      // POPIA: the sign-up form's (unticked) "news and announcements" box. Recorded either
-      // way, so they aren't asked again at their first login.
-      await require('../utils/privacy').setNewsPreferences(
-        user.id,
-        { email: newsOptIn === true, whatsapp: newsOptIn === true },
-        { source: 'signup', ip: getClientIp(req), answered: true, logAll: true },
-      ).catch(e => console.warn('[signup] news preference not saved:', e?.message || e));
-      // The sign-up form requires ticking "I agree to the Terms of Use and Privacy Policy".
-      await require('../utils/privacyNotice').acceptNotice(user.id, { source: 'signup', ip: getClientIp(req) })
-        .catch(e => console.warn('[signup] notice acceptance not saved:', e?.message || e));
-
-
-      // Send welcome email in the background — don't block the response
-      sendWelcomeEmail(user).catch(() => {});
-
-      res.status(201).json({
-        id: user.id,
-        name: user.name,
-        email: user.email,
-        role: user.role,
-        token: generateToken(user.id, user.role, user.tokenVersion)
-      });
-    } else {
-      res.status(400);
-      throw new Error('Invalid user data');
-    }
+    res.status(201).json(await accounts.signUp(req.body || {}, { ip: getClientIp(req), userAgent: req.headers['user-agent'] }));
   } catch (error) {
-    res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(error) });
+    res.status(errorStatus(error, res)).json({ message: safeErrorMessage(error) });
   }
 };
 
@@ -260,108 +49,12 @@ const registerUser = async (req, res) => {
 // @access  Public
 const loginUser = async (req, res) => {
   try {
-    const {email, password, deviceToken} = req.body;
-
-    const rawInput = email;
-
-    // Normalize phone input — convert SA local format (0xx) → international (27xx)
-    const { normalizeZAPhone } = require('../utils/whatsapp');
-    const normalizedPhone = normalizeZAPhone(rawInput) || rawInput.replace(/\D/g, '');
-
-    // Check for user email or phone
-    const user = await prisma.user.findFirst({
-      where: {
-        OR: [
-          { email: rawInput },
-          ...(normalizedPhone ? [{ phoneNumber: normalizedPhone }] : []),
-        ]
-      }
-    });
-
-    if (!user) {
-      res.status(401);
-      throw new Error('User does not exist');
+    const { email, password, deviceToken } = req.body || {};
+    const result = await accounts.logIn({ identifier: email, password, deviceToken }, { ip: getClientIp(req), userAgent: req.headers['user-agent'] });
+    if (result.status === 'code_required') {
+      return res.json({ twoFactorRequired: true, ...(result.enrolling ? { enrolling: true } : {}), ...result.challenge });
     }
-
-    // Check if user is active
-    if (!user.isActive) {
-      // Resend the activation link on each failed login attempt against an inactive
-      // account, in case the original one (sent at creation, or a prior attempt) expired.
-      await sendActivationLink(user);
-      // If the account has a real email (not a guest placeholder), it went out via email
-      if (user.email && !user.email.endsWith('@guest.local')) {
-        res.status(401);
-        throw new Error('Your account is not yet active. We\'ve sent you an email with a link to activate your account.');
-      }
-      // No real email — if they have a phone number, it went out via WhatsApp
-      if (user.phoneNumber) {
-        res.status(401);
-        throw new Error('Your account is not yet active. We\'ve sent you a WhatsApp message with a link to activate your account.');
-      }
-      res.status(401);
-      throw new Error('Your account has been deactivated');
-    }
-
-    const MAX_ATTEMPTS = 5;
-    const LOCK_TIME = 5 * 60 * 1000; // 5 min
-
-    // Check lock
-    if (user.lockUntil && user.lockUntil > new Date()) {
-      const now = new Date().getTime();
-      const lockTime = new Date(user.lockUntil).getTime();
-
-      const diffMs = lockTime - now;
-      const diffMinutes = Math.ceil(diffMs / (1000 * 60));
-
-      throw new Error(`Too many attempts. Try again in ${diffMinutes} minute(s).`);
-    }
-
-    // Check password
-    const isMatch = await comparePassword(password, user.password);
-
-    if (!isMatch) {
-      const attempts = user.failedAttempts + 1;
-
-      await prisma.user.update({
-        where: { id: user.id },
-        data: {
-          failedAttempts: attempts,
-          lockUntil:
-              attempts >= MAX_ATTEMPTS
-                  ? new Date(Date.now() + LOCK_TIME)
-                  : null,
-        },
-      });
-
-      throw new Error("Invalid email or password");
-    }
-
-    // ✅ SUCCESS → reset attempts
-    const updated = await prisma.user.update({
-      where: { id: user.id },
-      data: { failedAttempts: 0, lockUntil: null },
-      select: LOGIN_USER_SELECT,
-    });
-
-    // Two-factor: the password alone isn't enough unless this browser was
-    // remembered earlier. Send a code and hand back a challenge instead of a token.
-    if (updated.twoFactorEnabled && !(await isTrustedDevice(updated.id, deviceToken))) {
-      const challenge = await createChallenge(updated, 'login', updated.twoFactorMethod || 'email');
-      return res.json({ twoFactorRequired: true, ...challenge });
-    }
-
-    // Admins and supervisors must use 2FA. Not set up yet: send a code to the
-    // first channel that can deliver one, and verifying it turns 2FA on. A
-    // trusted device can't skip this — nothing has been verified yet.
-    if (!updated.twoFactorEnabled && requiresTwoFactor(updated)) {
-      const method = await enforcementMethod(updated);
-      if (method) {
-        const challenge = await createChallenge(updated, 'login', method);
-        return res.json({ twoFactorRequired: true, enrolling: true, ...challenge });
-      }
-    }
-
-    await completeLogin(updated, req, res);
+    res.json(result.session);
   } catch (error) {
     res.status(errorStatus(error, res)).json({ message: safeErrorMessage(error) });
   }
@@ -373,30 +66,7 @@ const loginUser = async (req, res) => {
 const verifyLoginTwoFactor = async (req, res) => {
   try {
     const { challengeId, code, rememberDevice } = req.body || {};
-    const challenge = await verifyChallenge(challengeId, code, 'login');
-
-    let user = await prisma.user.findUnique({ where: { id: challenge.userId }, select: LOGIN_USER_SELECT });
-    if (!user || !user.isActive) {
-      res.status(401);
-      throw new Error('Your account has been deactivated');
-    }
-
-    // First login since 2FA became required for this role: the code proves the
-    // channel works, so turn 2FA on with it.
-    if (!user.twoFactorEnabled && requiresTwoFactor(user)) {
-      user = await prisma.user.update({
-        where: { id: user.id },
-        data: { twoFactorEnabled: true, twoFactorMethod: challenge.method, updatedAt: new Date() },
-        select: LOGIN_USER_SELECT,
-      });
-      logSecurityEvent({ userId: user.id, type: 'two_factor_enabled', ip: getClientIp(req), userAgent: req.headers['user-agent'] }).catch(() => {});
-    }
-
-    const extra = {};
-    if (rememberDevice === true) {
-      extra.deviceToken = await issueTrustedDevice(user.id, req.headers['user-agent']);
-    }
-    await completeLogin(user, req, res, extra);
+    res.json(await accounts.verifyLoginCode({ challengeId, code, rememberDevice }, { ip: getClientIp(req), userAgent: req.headers['user-agent'] }));
   } catch (error) {
     res.status(errorStatus(error, res)).json({ message: safeErrorMessage(error) });
   }
@@ -565,114 +235,10 @@ const getUserProfile = async (req, res) => {
 // @access  Private
 const updateUserProfile = async (req, res) => {
   try {
-    const user = await prisma.user.findUnique({
-      where: { id: req.user.id }
-    });
-
-    if (!user) {
-      res.status(404);
-      throw new Error('User not found');
-    }
-
-    const { name, email, password, phoneNumber, currentPassword, notificationPreference, homeCampusId } = req.body || {};
-
-    // Home campus (only while campuses are on): an active campus, or ''/null for none.
-    let newHomeCampusId = user.homeCampusId;
-    if (homeCampusId !== undefined && await require('../utils/campuses').campusesEnabled()) {
-      if (!homeCampusId) newHomeCampusId = null;
-      else {
-        const campus = await prisma.campus.findFirst({ where: { id: String(homeCampusId), archivedAt: null }, select: { id: true } });
-        if (!campus) { res.status(400); throw new Error('Choose one of the campuses in the list.'); }
-        newHomeCampusId = campus.id;
-      }
-    }
-
-    // If a password change is requested, verify current password for safety
-    let newHashedPassword = undefined;
-    if (typeof password === 'string' && password.trim().length > 0) {
-      const newPw = password.trim();
-      if (!currentPassword || typeof currentPassword !== 'string' || currentPassword.length === 0) {
-        res.status(400);
-        throw new Error('Current password is required to set a new password');
-      }
-      const matches = await comparePassword(currentPassword, user.password);
-      if (!matches) {
-        res.status(400);
-        throw new Error('Current password is incorrect');
-      }
-      if (newPw.length < 8) {
-        res.status(400);
-        throw new Error('New password must be at least 8 characters long');
-      }
-      newHashedPassword = await hashPassword(newPw);
-    }
-
-    // Normalize phone
-    const { normalizeZAPhone } = require('../utils/whatsapp');
-    let newPhone = user.phoneNumber;
-    if (phoneNumber !== undefined) {
-      newPhone = phoneNumber ? (normalizeZAPhone(phoneNumber) || phoneNumber.replace(/\D/g, '') || null) : null;
-    }
-
-    // Validate notification preference — WhatsApp requires a valid SA phone number
-    const { resolveNotificationPreference } = require('../utils/notificationPreference');
-    const newPref = resolveNotificationPreference(notificationPreference, newPhone, user.notificationPreference);
-
-    // 2FA codes can't go to WhatsApp without a usable number — move them to email
-    // rather than leave the account pointing at a channel that no longer exists.
-    const { isValidZAPhone } = require('../utils/whatsapp');
-    const newTwoFactorMethod = user.twoFactorMethod === 'whatsapp' && !isValidZAPhone(newPhone) ? 'email' : user.twoFactorMethod;
-
-    // Update user data
-    const updatedUser = await prisma.user.update({
-      where: { id: req.user.id },
-      data: {
-        name: name || user.name,
-        email: email || user.email,
-        password: newHashedPassword ? newHashedPassword : user.password,
-        phoneNumber: newPhone,
-        notificationPreference: newPref,
-        twoFactorMethod: newTwoFactorMethod,
-        homeCampusId: newHomeCampusId,
-        updatedAt: new Date()
-      },
-      select: {
-        id: true,
-        name: true,
-        email: true,
-        role: true,
-        phoneNumber: true,
-        notificationPreference: true,
-        twoFactorEnabled: true,
-        twoFactorMethod: true,
-        createdAt: true,
-        updatedAt: true,
-        isActive: true,
-        homeCampusId: true,
-        tokenVersion: true
-      }
-    });
-
-    // If the password was changed, send a security alert email (fire-and-forget)
-    if (newHashedPassword) {
-      await clearTrustedDevices(updatedUser.id);
-      const { sendMail, buildPasswordChangedEmail } = require('../utils/email');
-      const supportEmail = getSettingSync('org_email', process.env.EMAIL_FROM || '');
-      const content = buildPasswordChangedEmail({ name: updatedUser.name, when: Date.now(), supportEmail });
-      sendMail({ to: updatedUser.email, subject: `Your ${getOrgName()} password was changed`, ...content })
-        .catch(e => console.warn('[email] Failed to send password changed alert:', e?.message || e));
-      const { waText } = require('../utils/notify');
-      waText(updatedUser, content.text).catch(() => {});
-      logSecurityEvent({ userId: updatedUser.id, type: 'password_changed', ip: getClientIp(req), userAgent: req.headers['user-agent'] }).catch(() => {});
-    }
-
-    res.json({
-      ...updatedUser,
-      twoFactorRequired: requiresTwoFactor(updatedUser),
-      token: generateToken(updatedUser.id, updatedUser.role, updatedUser.tokenVersion)
-    });
+    const { user, twoFactorRequired, token } = await accounts.updateProfile(req.user.id, req.body || {}, { ip: getClientIp(req), userAgent: req.headers['user-agent'] });
+    res.json({ ...user, twoFactorRequired, token });
   } catch (error) {
-    res.status(res.statusCode === 200 ? 400 : res.statusCode).json({ message: safeErrorMessage(error) });
+    res.status(errorStatus(error, res)).json({ message: safeErrorMessage(error) });
   }
 };
 
@@ -1114,6 +680,13 @@ const activateAccount = async (req, res) => {
       select: { id: true, name: true, email: true, role: true, tokenVersion: true }
     });
 
+    // The activation form asks them to agree to the terms and privacy notice, as sign-up does.
+    // Without it (an older page) they're asked once after login instead.
+    if (req.body.acceptTerms === true) {
+      await require('../utils/privacyNotice').acceptNotice(user.id, { source: 'activation', ip: getClientIp(req) })
+        .catch(e => console.warn('[activate] notice acceptance not saved:', e?.message || e));
+    }
+
     // Send welcome email (skip guest/placeholder accounts)
     if (updated.email && !updated.email.endsWith('@guest.local')) {
       sendWelcomeEmail(updated).catch(() => {});

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,
+};

backend/src/hub/client.js

@@ -1,10 +1,12 @@
 /**
  * Talking to the Cross Events Hub (docs/hub-protocol.md): register with a licence key, then a
- * signed heartbeat every 15 minutes, and a signed update request when an admin asks for one.
- * Install → Hub only. Stored in AppSetting:
+ * signed heartbeat every 15 minutes, and a signed update request (or withdrawal) when an admin
+ * asks. Install → Hub only. Stored in AppSetting:
  *   hub_install_id, hub_install_secret (encrypted), hub_licence (signed token),
  *   hub_last_heartbeat_at, hub_last_error, hub_latest_version,
- *   hub_update_requested_at, hub_update_requested_version.
+ *   hub_releases, hub_notices (JSON from the last heartbeat: what's new, provider's notices),
+ *   hub_update_requested_at, hub_update_requested_version,
+ *   hub_update_snoozed_version ("Not now" for that version; set here, not by the Hub).
  * These keys are kept out of the generic settings endpoints (settingsController).
  */
 
@@ -16,7 +18,7 @@ const report = require('./report');
 
 const PROTOCOL_VERSION = 1;
 const TIMEOUT_MS = 15000;
-const HUB_KEYS = ['hub_install_id', 'hub_install_secret', 'hub_licence', 'hub_last_heartbeat_at', 'hub_last_error', 'hub_latest_version', 'hub_update_requested_at', 'hub_update_requested_version'];
+const HUB_KEYS = ['hub_install_id', 'hub_install_secret', 'hub_licence', 'hub_last_heartbeat_at', 'hub_last_error', 'hub_latest_version', 'hub_update_requested_at', 'hub_update_requested_version', 'hub_releases', 'hub_notices', 'hub_update_snoozed_version'];
 
 function hubUrl() {
   return String(process.env.HUB_URL || 'https://events-hub.crosscode.co.za').replace(/\/$/, '');
@@ -38,6 +40,14 @@ async function save(values) {
   clearLicenceCache();
 }
 
+/** What's new and the provider's notices from a register/heartbeat reply (a Hub before 1.4.0 sends neither). */
+function fromHub(data) {
+  return {
+    hub_releases: Array.isArray(data.releases) ? JSON.stringify(data.releases.slice(0, 20)) : null,
+    hub_notices: Array.isArray(data.notices) ? JSON.stringify(data.notices.slice(0, 20)) : null,
+  };
+}
+
 async function read(keys) {
   const rows = await prisma.appSetting.findMany({ where: { key: { in: keys } } });
   return Object.fromEntries(rows.map(r => [r.key, r.value]));
@@ -101,6 +111,7 @@ async function connect(licenceKey, adminContact) {
     hub_last_heartbeat_at: new Date().toISOString(),
     hub_last_error: null,
     hub_latest_version: data.latestVersion || null,
+    ...fromHub(data),
   });
   return claims;
 }
@@ -119,6 +130,7 @@ async function heartbeat() {
       hub_last_heartbeat_at: new Date().toISOString(),
       hub_last_error: null,
       hub_latest_version: data.latestVersion || null,
+      ...fromHub(data),
     });
     return { ok: true, status: claims?.status || null };
   } catch (e) {
@@ -133,22 +145,57 @@ async function heartbeat() {
   }
 }
 
+/** a < b as x.y.z versions. */
+function olderThan(a, b) {
+  const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0);
+  const pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] < pb[i];
+  return false;
+}
+
 /**
  * Ask the Hub for this site to be updated (§3a). Joshua is told; the site never updates itself.
- * Returns { requestedAt, version, alreadyRequested }.
+ * Asking again after a newer version came out moves the request on to it (`changed`). A Hub before
+ * 1.5.0 can't do that (it doesn't send `changed`), so the old request is withdrawn and made again.
+ * Returns { requestedAt, version, alreadyRequested, changed, previousVersion }.
  */
 async function requestUpdate() {
-  let data;
-  try {
-    data = await signedPost('/api/installs/update-request', { protocolVersion: PROTOCOL_VERSION, version: report.APP_VERSION });
-  } catch (e) {
-    if (e.code === 'NOT_FOUND') throw new HubError('The Hub doesn\'t take update requests yet. Please contact your provider.', 'NOT_SUPPORTED', 502);
-    throw e;
+  const ask = async () => {
+    try {
+      return await signedPost('/api/installs/update-request', { protocolVersion: PROTOCOL_VERSION, version: report.APP_VERSION });
+    } catch (e) {
+      if (e.code === 'NOT_FOUND') throw new HubError('The Hub doesn\'t take update requests yet. Please contact your provider.', 'NOT_SUPPORTED', 502);
+      throw e;
+    }
+  };
+  let data = await ask();
+  if (data.alreadyRequested && data.changed === undefined) {
+    const asked = (await read(['hub_update_requested_version'])).hub_update_requested_version || null;
+    if (!asked || olderThan(asked, data.version)) {
+      await cancelUpdateRequest();
+      data = { ...(await ask()), changed: true, previousVersion: asked };
+    }
   }
   await save({ hub_update_requested_at: data.requestedAt, hub_update_requested_version: data.version || null });
   return data;
 }
 
+/** Withdraw the update request (§3a): the provider is told not to update after all. */
+async function cancelUpdateRequest() {
+  try {
+    await signedPost('/api/installs/update-request/cancel', { protocolVersion: PROTOCOL_VERSION });
+  } catch (e) {
+    if (e.code === 'NOT_FOUND') throw new HubError('The Hub can\'t withdraw update requests yet. Please contact your provider.', 'NOT_SUPPORTED', 502);
+    throw e;
+  }
+  await save({ hub_update_requested_at: null, hub_update_requested_version: null });
+}
+
+/** "Not now": no update reminders until a newer version than `version` is out. Null turns them back on. */
+async function snoozeUpdate(version) {
+  await save({ hub_update_snoozed_version: version || null });
+}
+
 /**
  * A heartbeat soon (on startup, and after connecting), so a licence change on the Hub shows
  * without waiting for the next 15-minute run. Never throws; skipped when the job is switched off.
@@ -164,4 +211,4 @@ function heartbeatSoon(delayMs = 30 * 1000) {
   soonTimer.unref?.();
 }
 
-module.exports = { PROTOCOL_VERSION, HUB_KEYS, hubUrl, HubError, connect, heartbeat, heartbeatSoon, requestUpdate };
+module.exports = { PROTOCOL_VERSION, HUB_KEYS, hubUrl, HubError, connect, heartbeat, heartbeatSoon, requestUpdate, cancelUpdateRequest, snoozeUpdate };

backend/src/hub/licence.js

@@ -77,10 +77,19 @@ function checkDisabled() {
 
 let cache = null;
 
+function parseList(json) {
+  try {
+    const list = JSON.parse(json || '[]');
+    return Array.isArray(list) ? list : [];
+  } catch {
+    return [];
+  }
+}
+
 /** This install's licence: claims, state and Hub connection details. Cached for 30 s. */
 async function licenceStatus({ fresh = false } = {}) {
   if (!fresh && cache && Date.now() - cache.at < CACHE_MS) return cache.value;
-  const rows = await prisma.appSetting.findMany({ where: { key: { in: ['hub_install_id', 'hub_licence', 'hub_last_heartbeat_at', 'hub_last_error', 'hub_latest_version', 'hub_update_requested_at', 'hub_update_requested_version'] } } });
+  const rows = await prisma.appSetting.findMany({ where: { key: { in: ['hub_install_id', 'hub_licence', 'hub_last_heartbeat_at', 'hub_last_error', 'hub_latest_version', 'hub_update_requested_at', 'hub_update_requested_version', 'hub_releases', 'hub_notices', 'hub_update_snoozed_version'] } } });
   const s = Object.fromEntries(rows.map(r => [r.key, r.value]));
   const claims = verifyToken(s.hub_licence);
   const value = {
@@ -95,6 +104,9 @@ async function licenceStatus({ fresh = false } = {}) {
     latestVersion: s.hub_latest_version || null,
     updateRequestedAt: s.hub_update_requested_at || null,
     updateRequestedVersion: s.hub_update_requested_version || null,
+    updateSnoozedVersion: s.hub_update_snoozed_version || null,
+    releases: parseList(s.hub_releases),
+    notices: parseList(s.hub_notices),
   };
   cache = { at: Date.now(), value };
   return value;

backend/src/hub/readOnly.js

@@ -13,6 +13,14 @@ const { licenceStatus } = require('./licence');
 const BLOCKED = [
   ['POST', /^\/api\/events\/?$/],
   ['PUT', /^\/api\/events\/[^/]+\/?$/],
+  ['POST', /^\/api\/events\/[^/]+\/copy-from\/?$/],
+  ['POST', /^\/api\/series\/?$/],
+  ['PUT', /^\/api\/series\/[^/]+\/?$/],
+  // Season passes: new or changed passes, and buying one (it makes registrations and payments).
+  ['POST', /^\/api\/season-passes\/?$/],
+  ['PUT', /^\/api\/season-passes\/[^/]+\/?$/],
+  ['POST', /^\/api\/season-passes\/[^/]+\/buy\/?$/],
+  ['POST', /^\/api\/season-passes\/purchases\/[^/]+\/checkout\/?$/],
   ['POST', /^\/api\/events\/[^/]+\/options\/?$/],
   ['PUT', /^\/api\/events\/options\/[^/]+\/?$/],
   ['POST', /^\/api\/events\/options\/[^/]+\/variants\/?$/],
@@ -26,6 +34,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) {

backend/src/jobs/index.js

@@ -15,10 +15,13 @@
  * same jobs run on in-process timers instead, as before.
  */
 
-const cronParser = require('cron-parser');
+const { CronExpressionParser } = require('cron-parser');
 
 const TIMEZONE = process.env.APP_TIMEZONE || 'Africa/Johannesburg';
-const SCHEMA = 'pgboss';
+// pg-boss 11 can't upgrade pg-boss 10's schema (it migrates only from 11.0), so it has its own.
+// The old `pgboss` schema (10.x) is left as it was; it can be dropped (DROP SCHEMA pgboss CASCADE)
+// once 1.51.7 has run — it only held queued runs and their history.
+const SCHEMA = 'pgboss_v11';
 
 const JOBS = [
   {
@@ -45,6 +48,18 @@ 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: 'webhooks', label: 'Outbound webhooks: send what is due, retry failures, delete deliveries after 30 days', cron: '* * * * *', env: 'WEBHOOKS_JOBS_ENABLED',
+    run: () => require('../utils/webhooks').runJob(),
+  },
+  {
+    name: 'series', label: 'Event series: tell followers when a new event goes live', cron: '*/15 * * * *', env: 'SERIES_JOBS_ENABLED',
+    run: () => require('../utils/series').runAnnounceJob(),
+  },
   {
     name: 'consent', label: 'Parental consent reminders and medical-detail deletion', cron: '0 9 * * *', env: 'CONSENT_JOBS_ENABLED',
     run: async () => {
@@ -93,7 +108,7 @@ function cronFor(job) {
   const override = process.env[`JOB_SCHEDULE_${job.name.toUpperCase().replace(/-/g, '_')}`];
   if (override) {
     try {
-      cronParser.parseExpression(override, { tz: TIMEZONE });
+      CronExpressionParser.parse(override, { tz: TIMEZONE });
       return override;
     } catch {
       console.warn(`[jobs] Ignoring invalid schedule for ${job.name}: "${override}"`);
@@ -104,7 +119,7 @@ function cronFor(job) {
 
 /** When a cron schedule next fires after `from`. */
 function nextRun(cron, from = new Date()) {
-  return cronParser.parseExpression(cron, { tz: TIMEZONE, currentDate: from }).next().toDate();
+  return CronExpressionParser.parse(cron, { tz: TIMEZONE, currentDate: from }).next().toDate();
 }
 
 function summarize(result) {
@@ -258,11 +273,8 @@ async function jobStatus(prisma) {
       FROM (
         SELECT name, state, created_on, started_on, completed_on, output,
                row_number() OVER (PARTITION BY name ORDER BY created_on DESC) AS rn
-        FROM (
-          SELECT name, state::text, created_on, started_on, completed_on, output FROM ${SCHEMA}.job
-          UNION ALL
-          SELECT name, state::text, created_on, started_on, completed_on, output FROM ${SCHEMA}.archive
-        ) all_jobs
+        -- pg-boss 11 keeps finished runs in job until they expire (there's no archive table).
+        FROM (SELECT name, state::text, created_on, started_on, completed_on, output FROM ${SCHEMA}.job) all_jobs
         WHERE name = ANY($1::text[])
       ) ranked
       WHERE rn <= 10

backend/src/payments/status.js

@@ -19,6 +19,12 @@ async function checkoutPaid(checkout) {
   const refs = [checkout.id, checkout.externalId].filter(Boolean);
   const tx = await prisma.providerTransaction.findFirst({ where: { checkoutId: { in: refs }, paymentId: { not: null } }, select: { id: true } });
   if (tx) return true;
+  // A season pass checkout: paid once its purchase is.
+  const purchaseId = checkout.metadata?.purchaseId;
+  if (purchaseId) {
+    const purchase = await prisma.seasonPassPurchase.findUnique({ where: { id: String(purchaseId) }, select: { status: true } });
+    return purchase?.status === 'paid';
+  }
   const registrationId = checkout.metadata?.registrationId;
   if (!registrationId) return false;
   const reg = await prisma.registration.findUnique({ where: { id: String(registrationId) }, select: { status: true } });

backend/src/payments/webhook.js

@@ -71,7 +71,9 @@ const handleProviderWebhook = (providerId) => async (req, res) => {
         if (!existingRegistration) {
           const meta = tx.metadata || {};
           const isDonation = meta.type === 'donation' || !!meta.isDonation || !!meta.eventId;
-          if (!isDonation) {
+          // A season pass checkout belongs to its purchase, not to one registration.
+          const isSeasonPass = meta.type === 'season_pass' && !!meta.purchaseId;
+          if (!isDonation && !isSeasonPass) {
             try { await saveProviderTransaction(provider.id, event, body); } catch (e) { console.warn('Failed to save unreconciled transaction:', e?.message || e); }
             return res.status(200).json({
               success: true,
@@ -141,6 +143,11 @@ async function recordSucceededPayment(providerId, event, body) {
     return { status: 'already_processed', paymentId: existingPayment.id, externalId };
   }
 
+  // Season pass: split over the purchase's registrations, one Payment per event.
+  if (metadata.type === 'season_pass' && metadata.purchaseId) {
+    return require('../utils/seasonPass').recordPassPayment(providerId, event, body);
+  }
+
   let registration = null;
   const refs = event.checkoutRefs || [checkoutId].filter(Boolean);
   if (refs.length) registration = await prisma.registration.findFirst({ where: { checkoutId: { in: refs } }, include: REG_INCLUDE });

backend/src/routes/dashboardRoutes.js

@@ -0,0 +1,23 @@
+const express = require('express');
+const router = express.Router();
+const { protect, staff } = require('../middleware/authMiddleware');
+const { scopeList } = require('../utils/campusScope');
+const dashboard = require('../utils/dashboard');
+
+// Both follow the person's campus scope inside utils/dashboard.js.
+
+// @desc    Today's events and how they're going, money in, and what's waiting (1.49.0)
+// @route   GET /api/dashboard/today
+// @access  Private/Staff (money and waiting items for supervisors and admins)
+router.get('/today', protect, staff, scopeList, async (req, res) => {
+  try { res.json(await dashboard.today(req)); } catch (e) { res.status(400).json({ message: e.message }); }
+});
+
+// @desc    Command palette search (?q=): events; supervisors also payments by amount; admins people and registrations
+// @route   GET /api/dashboard/search
+// @access  Private/Staff
+router.get('/search', protect, staff, scopeList, async (req, res) => {
+  try { res.json({ results: await dashboard.search(req, req.query.q) }); } catch (e) { res.status(400).json({ message: e.message }); }
+});
+
+module.exports = router;

backend/src/routes/eventRoutes.js

@@ -2,6 +2,7 @@ const express = require('express');
 const router = express.Router();
 const {
   createEvent,
+  copyEventSetupFrom,
   getEvents,
   getAllEvents,
   getEventsAll,
@@ -29,7 +30,7 @@ const {
   getEventByAlias
 } = require('../controllers/eventController');
 const { protect, admin, supervisor, optionalAuth } = require('../middleware/authMiddleware');
-const { scopeEvent, scopeList } = require('../utils/campusScope');
+const { scopeEvent, scopeBody, scopeList } = require('../utils/campusScope');
 
 // Public routes
 router.get('/', getEvents);
@@ -55,6 +56,9 @@ router.route('/:id')
   .put(protect, supervisor, scopeEvent({ need: 'manage' }), updateEvent)
   .delete(protect, admin, deleteEvent);
 
+// Clone: copy allocation groups (and costs, for admins) from the source event into a new copy.
+router.post('/:id/copy-from', protect, supervisor, scopeEvent({ need: 'manage' }), scopeBody([['fromEventId', 'event']]), copyEventSetupFrom);
+
 // Notification recipients: who gets registration/payment/daily-summary emails for this event
 router.route('/:id/notify-recipients')
   .get(protect, supervisor, scopeEvent(), getEventNotifyRecipients)

backend/src/routes/hubRoutes.js

@@ -1,7 +1,8 @@
 const express = require('express');
 const router = express.Router();
-const { getStatus, connect, heartbeatNow, requestUpdate } = require('../controllers/hubController');
-const { protect, admin } = require('../middleware/authMiddleware');
+const { getStatus, connect, heartbeatNow, requestUpdate, cancelUpdateRequest, snoozeUpdate, getNotices } = require('../controllers/hubController');
+const { protect, admin, supervisor } = require('../middleware/authMiddleware');
+const { campusIndependent } = require('../utils/campusScope');
 
 // Licence and the Cross Events Hub (docs/hub-protocol.md). Admins only; the setup wizard's
 // admin token counts, so the licence step can run during /setup.
@@ -9,5 +10,9 @@ router.get('/status', protect, admin, getStatus);
 router.post('/connect', protect, admin, connect);
 router.post('/heartbeat', protect, admin, heartbeatNow);
 router.post('/update-request', protect, admin, requestUpdate);
+router.post('/update-request/cancel', protect, admin, cancelUpdateRequest);
+router.post('/update-snooze', protect, admin, snoozeUpdate);
+// The provider's notices: site admins and supervisors see them as a banner.
+router.get('/notices', protect, supervisor, campusIndependent('notices from the provider are for the whole site'), getNotices);
 
 module.exports = router;

backend/src/routes/outboundWebhookRoutes.js

@@ -0,0 +1,17 @@
+const express = require('express');
+const router = express.Router();
+const { list, create, update, remove, rotateSecret, test, deliveries, resend } = require('../controllers/outboundWebhookController');
+const { protect, admin } = require('../middleware/authMiddleware');
+
+// Outbound webhooks (1.48.0): admins only. Payment provider webhooks *into* the site are /api/webhooks/<provider>.
+router.use(protect, admin);
+router.get('/', list);
+router.post('/', create);
+router.post('/deliveries/:id/resend', resend);
+router.put('/:id', update);
+router.delete('/:id', remove);
+router.post('/:id/rotate-secret', rotateSecret);
+router.post('/:id/test', test);
+router.get('/:id/deliveries', deliveries);
+
+module.exports = router;

backend/src/routes/privacyRoutes.js

@@ -21,6 +21,7 @@ const {
   saveNoticeDraft,
   discardNoticeDraft,
   publishNotice,
+  markBuiltInReviewed,
   listOperators,
   createOperator,
   updateOperator,
@@ -64,6 +65,7 @@ router.get('/notice/draft', protect, admin, getNoticeDraft);
 router.put('/notice/draft', protect, admin, saveNoticeDraft);
 router.delete('/notice/draft', protect, admin, discardNoticeDraft);
 router.post('/notice/publish', protect, admin, publishNotice);
+router.post('/notice/builtin-reviewed', protect, admin, markBuiltInReviewed);
 
 // Admin: operator register, consent log, access log
 router.get('/operators', protect, admin, listOperators);

backend/src/routes/registrationRoutes.js

@@ -17,7 +17,8 @@ const {
   updateAttendees, sendAttendeeFormLink,
 } = require('../controllers/registrationController');
 const { protect, supervisor, staff, optionalAuth } = require('../middleware/authMiddleware');
-const { scopeEvent, scopeList } = require('../utils/campusScope');
+const { scopeEvent, scopeList, scopeBody } = require('../utils/campusScope');
+const { notOnSeasonPass } = require('../utils/seasonPass');
 
 // Campus-scoped staff (utils/campusScope.js). Routes open to the registration's owner as well
 // as to staff check staff against the registration's event, and let the owner through (ownerOk).
@@ -25,10 +26,10 @@ const { scopeEvent, scopeList } = require('../utils/campusScope');
 // Registration - auth optional when event doesn't require it
 router.post('/', optionalAuth, createRegistration);
 router.get('/myregistrations', protect, getUserRegistrations);
-router.put('/:id/options', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), updateRegistrationOptions);
+router.put('/:id/options', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), notOnSeasonPass, updateRegistrationOptions);
 router.delete('/:id', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), cancelRegistration);
 router.post('/:id/send-invoice', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), sendInvoice);
-router.post('/:id/coupon', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), applyCoupon);
+router.post('/:id/coupon', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), notOnSeasonPass, applyCoupon);
 router.delete('/:id/coupon', protect, staff, scopeEvent({ resolve: 'registration' }), removeCoupon);
 router.put('/:id/attendees', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), updateAttendees);
 router.post('/:id/attendees/:attendeeId/send-form-link', protect, scopeEvent({ resolve: 'registration', ownerOk: true }), sendAttendeeFormLink);
@@ -45,5 +46,9 @@ router.get('/', protect, staff, scopeList, getRegistrations);
 router.put('/:id', protect, staff, scopeEvent({ resolve: 'registration' }), updateRegistrationStatus);
 router.get('/event/:eventId', protect, staff, scopeEvent(), getRegistrationsByEvent);
 router.post('/manual', protect, supervisor, scopeEvent({ from: req => req.body?.eventId }), createManualRegistration);
+// Bulk actions (1.49.1): every ticked registration must be one this person may manage.
+router.post('/bulk', protect, supervisor, scopeBody([['registrationIds', 'registration']], { orphan: 'deny' }), async (req, res) => {
+  try { res.json(await require('../utils/bulkRegistrations').runBulk(req, req.body || {})); } catch (e) { res.status(e.statusCode || 400).json({ message: e.message }); }
+});
 
 module.exports = router;

backend/src/routes/savedFilterRoutes.js

@@ -0,0 +1,24 @@
+const express = require('express');
+const router = express.Router();
+const { protect, staff } = require('../middleware/authMiddleware');
+const { campusIndependent } = require('../utils/campusScope');
+const filters = require('../utils/savedFilters');
+
+const OWN = campusIndependent('a person\'s own saved filters (the lists they filter are campus-checked themselves)');
+const fail = (res, e) => res.status(e.statusCode || 400).json({ message: e.message });
+
+// Saved filters on list pages (1.49.2) — always the signed-in person's own.
+router.get('/', protect, staff, OWN, async (req, res) => {
+  try { res.json(await filters.list(req.user.id, req.query.page)); } catch (e) { fail(res, e); }
+});
+router.post('/', protect, staff, OWN, async (req, res) => {
+  try { res.status(201).json(await filters.save(req.user.id, req.body || {})); } catch (e) { fail(res, e); }
+});
+router.put('/:id', protect, staff, OWN, async (req, res) => {
+  try { res.json(await filters.update(req.user.id, req.params.id, req.body || {})); } catch (e) { fail(res, e); }
+});
+router.delete('/:id', protect, staff, OWN, async (req, res) => {
+  try { await filters.remove(req.user.id, req.params.id); res.json({ ok: true }); } catch (e) { fail(res, e); }
+});
+
+module.exports = router;

backend/src/routes/seasonPassRoutes.js

@@ -0,0 +1,18 @@
+const express = require('express');
+const router = express.Router();
+const { listPasses, createPass, updatePass, deletePass, buy, payPurchase, myPurchases } = require('../controllers/seasonPassController');
+const { protect, supervisor } = require('../middleware/authMiddleware');
+const { campusIndependent } = require('../utils/campusScope');
+
+const SPANS = campusIndependent('a pass can span campuses; each event on it is checked against the person\'s campuses in the controller');
+
+router.get('/mine', protect, myPurchases);
+router.post('/:id/buy', protect, buy);
+router.post('/purchases/:id/checkout', protect, payPurchase);
+
+router.get('/', protect, supervisor, SPANS, listPasses);
+router.post('/', protect, supervisor, SPANS, createPass);
+router.put('/:id', protect, supervisor, SPANS, updatePass);
+router.delete('/:id', protect, supervisor, SPANS, deletePass);
+
+module.exports = router;

backend/src/routes/seriesRoutes.js

@@ -0,0 +1,21 @@
+const express = require('express');
+const router = express.Router();
+const { listSeries, createSeries, updateSeries, deleteSeries, getSeriesBySlug, followSeries, unfollowSeries, compare } = require('../controllers/seriesController');
+const { protect, admin, supervisor, optionalAuth } = require('../middleware/authMiddleware');
+const { campusIndependent, scopeList } = require('../utils/campusScope');
+
+const SPANS = campusIndependent('a series spans campuses; adding an event to one is checked on the event');
+
+router.get('/by-slug/:slug', optionalAuth, getSeriesBySlug);
+router.post('/:id/follow', protect, followSeries);
+router.delete('/:id/follow', protect, unfollowSeries);
+
+// The list filters each series' events by the person's campuses itself.
+router.get('/', protect, supervisor, SPANS, listSeries);
+router.post('/', protect, supervisor, SPANS, createSeries);
+router.put('/:id', protect, supervisor, SPANS, updateSeries);
+router.delete('/:id', protect, admin, deleteSeries);
+// Year-on-year report: only the events the person may see (filtered in the controller).
+router.get('/:id/compare', protect, supervisor, scopeList, compare);
+
+module.exports = router;

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;

backend/src/services/auth.ts

@@ -0,0 +1,349 @@
+/**
+ * Accounts: sign up, log in (with the 2FA code step) and changing your own details (1.51.2).
+ * Moved from userController.js so /api/users/* (v1) and /api/v2/auth/*, /api/v2/me share it.
+ */
+import { v4 as uuidv4 } from 'uuid';
+import axios from 'axios';
+import { prisma } from '../v2/legacy';
+import { fail, ServiceError } from './errors';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- the JS helpers below aren't typed yet */
+const auth = require('../config/auth') as {
+  generateToken(id: string, role: string, tokenVersion: number): string;
+  hashPassword(pw: string): Promise<string>;
+  comparePassword(pw: string, hash: string): Promise<boolean>;
+};
+const twoFactor = require('../utils/twoFactor') as {
+  createChallenge(user: any, purpose: string, method: string): Promise<{ challengeId: string; method: string; destination: string | null }>;
+  verifyChallenge(challengeId: string, code: string, purpose: string): Promise<{ userId: string; method: string }>;
+  issueTrustedDevice(userId: string, userAgent?: string): Promise<string>;
+  isTrustedDevice(userId: string, deviceToken?: string): Promise<boolean>;
+  clearTrustedDevices(userId: string): Promise<unknown>;
+  requiresTwoFactor(user: { role: string }): boolean;
+  enforcementMethod(user: any): Promise<string | null>;
+};
+const { logSecurityEvent } = require('../utils/securityEvents') as { logSecurityEvent(e: object): Promise<unknown> };
+const { getSettingSync } = require('../utils/settingsCache') as { getSettingSync(key: string, fallback: string): string };
+const whatsapp = () => require('../utils/whatsapp') as { normalizeZAPhone(p: unknown): string | null; isValidZAPhone(p: unknown): boolean };
+
+/** Who is asking, for security notices and the activity log. */
+export type RequestInfo = { ip?: string; userAgent?: string };
+
+// Org name for email subjects — falls back to Cross Code (the platform vendor)
+// rather than any specific customer's name when unconfigured.
+export function getOrgName(): string {
+  return getSettingSync('org_name', process.env.ORG_NAME || 'Cross Code');
+}
+
+const PRIVATE_IP_RE = /^(::1|::ffff:127\.|127\.|10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/;
+const frontendUrl = () => (process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');
+
+/**
+ * Fire-and-forget: create a 24h activation token and deliver it to an inactive account — by
+ * email if it has a real (non-guest) address, otherwise by WhatsApp if it has a phone number.
+ * Used when a login hits an inactive account, and when staff create an account for someone.
+ */
+export async function sendActivationLink(user: { id: string; name?: string | null; email?: string | null; phoneNumber?: string | null }): Promise<void> {
+  const hasRealEmail = !!(user?.email && !user.email.endsWith('@guest.local'));
+  if (!hasRealEmail && !user?.phoneNumber) return;
+  try {
+    const token = uuidv4();
+    const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000);
+    await prisma.passwordReset.updateMany({ where: { userId: user.id, used: false }, data: { used: true } });
+    await prisma.passwordReset.create({ data: { id: uuidv4(), userId: user.id, token, expiresAt, used: false } });
+    const activationUrl = `${frontendUrl()}/activate-account?token=${encodeURIComponent(token)}`;
+
+    if (hasRealEmail) {
+      const { sendMail, buildAccountActivationEmail } = require('../utils/email');
+      const content = buildAccountActivationEmail({ name: user.name, activationUrl });
+      sendMail({ to: user.email, subject: `Activate your ${getOrgName()} account`, ...content })
+        .catch((e: any) => console.warn('[activation email] Failed:', e?.message || e));
+    } else {
+      const orgName = getOrgName();
+      const waMessage = [
+        `🔓 *Activate your ${orgName} account*`,
+        '',
+        `Hi ${user.name || 'there'},`,
+        '',
+        'Your account needs to be activated before you can log in. Tap the link below to set a password and activate your account:',
+        '',
+        activationUrl,
+        '',
+        '_This link expires in 24 hours._',
+      ].join('\n');
+      const { waTextAny } = require('../utils/notify');
+      waTextAny(user, waMessage).catch((e: any) => console.warn('[activation WA] Failed:', e?.message || e));
+    }
+  } catch (e: any) {
+    console.warn('[activation token] Failed to create activation token:', e?.message || e);
+  }
+}
+
+// Fire-and-forget: a login notice with the approximate place it came from.
+async function sendLoginNotification(user: any, info: RequestInfo): Promise<void> {
+  try {
+    const ip = info.ip || 'unknown';
+    const userAgent = info.userAgent || 'Unknown device';
+    const when = new Date().toLocaleString('en-ZA', { timeZone: 'Africa/Johannesburg' });
+
+    let location = 'Unknown location';
+    if (ip !== 'unknown' && !PRIVATE_IP_RE.test(ip)) {
+      try {
+        const geo = await axios.get(`http://ip-api.com/json/${ip}?fields=status,city,regionName,country`, { timeout: 3000 });
+        if (geo.data?.status === 'success') {
+          const parts = [geo.data.city, geo.data.regionName, geo.data.country].filter(Boolean);
+          if (parts.length) location = parts.join(', ');
+        }
+      } catch { /* geo lookup failure is non-fatal */ }
+    }
+
+    const { sendMail, buildLoginNotificationEmail } = require('../utils/email');
+    const { buildWALogin } = require('../utils/waMessages');
+    const content = buildLoginNotificationEmail({ name: user.name, when, location, userAgent });
+    // Security: always email; also WhatsApp if preferred
+    await sendMail({ to: user.email, subject: `New login to your ${getOrgName()} account`, ...content });
+    const { waText } = require('../utils/notify');
+    await waText(user, buildWALogin({ name: user.name, when, location, userAgent })).catch(() => {});
+  } catch (e: any) {
+    console.warn('[login notification] Failed:', e?.message || e);
+  }
+}
+
+/** Fire-and-forget: the welcome email, with the next few upcoming events. */
+export async function sendWelcomeEmail(user: any): Promise<void> {
+  try {
+    const events = await prisma.event.findMany({
+      where: { isActive: true, startDate: { gt: new Date() } },
+      orderBy: { startDate: 'asc' },
+      take: 3,
+      select: { title: true, startDate: true },
+    });
+    const { sendMail, buildWelcomeEmail } = require('../utils/email');
+    const { buildWAWelcome } = require('../utils/waMessages');
+    const content = buildWelcomeEmail({ name: user.name, events });
+    const { waText } = require('../utils/notify');
+    // Welcome is always sent via email; also via WhatsApp if preferred
+    await sendMail({ to: user.email, subject: `Welcome to ${getOrgName()}!`, ...content });
+    await waText(user, buildWAWelcome({ name: user.name, events })).catch(() => {});
+  } catch (e: any) {
+    console.warn('[welcome email] Failed:', e?.message || e);
+  }
+}
+
+// Fields the login flow needs once the password (and any 2FA code) has checked out.
+export const LOGIN_USER_SELECT = {
+  id: true, name: true, email: true, role: true, tokenVersion: true, isActive: true,
+  phoneNumber: true, notificationPreference: true, twoFactorEnabled: true, twoFactorMethod: true, newsAskedAt: true,
+  noticeVersionAccepted: true,
+} as const;
+
+type LoginUser = { id: string; name: string; email: string; role: string; tokenVersion: number; newsAskedAt: Date | null; noticeVersionAccepted: number | null } & Record<string, unknown>;
+
+export type Session = {
+  id: string; name: string; email: string; role: string; token: string;
+  newsPromptPending: boolean; noticePromptPending: false | 'first' | 'updated'; deviceToken?: string;
+};
+
+/**
+ * Final step of a successful login (after the password, and the 2FA code when required):
+ * notify, record the activity, and issue the session token.
+ */
+export async function completeLogin(user: LoginUser, info: RequestInfo, extra: { deviceToken?: string } = {}): Promise<Session> {
+  const noticePromptPending = await (require('../utils/privacyNotice') as { noticePromptPending(u: object): Promise<false | 'first' | 'updated'> }).noticePromptPending(user).catch(() => false as const);
+  // Retention: logging in keeps the account (and cancels an inactivity warning).
+  prisma.user.update({ where: { id: user.id }, data: { lastLoginAt: new Date(), inactivityWarnedAt: null } }).catch(() => {});
+  sendLoginNotification(user, info).catch(() => {});
+  logSecurityEvent({ userId: user.id, type: 'login', ip: info.ip, userAgent: info.userAgent }).catch(() => {});
+  return {
+    id: user.id,
+    name: user.name,
+    email: user.email,
+    role: user.role,
+    token: auth.generateToken(user.id, user.role, user.tokenVersion),
+    // POPIA: ask about News & announcements once (NewsPrompt on the frontend), and to accept a
+    // privacy notice version marked as a significant change (NoticePrompt).
+    newsPromptPending: !user.newsAskedAt,
+    noticePromptPending,
+    ...extra,
+  };
+}
+
+export type SignUpInput = { name: string; email: string; password: string; phoneNumber?: string | null; notificationPreference?: string; newsOptIn?: boolean };
+
+/** A new account (signed in straight away), with the news choice and privacy notice recorded. */
+export async function signUp(input: SignUpInput, info: RequestInfo) {
+  const { name, email, password, phoneNumber, notificationPreference, newsOptIn } = input;
+  const { normalizeZAPhone, isValidZAPhone } = whatsapp();
+  const phone = normalizeZAPhone(phoneNumber) || (phoneNumber ? phoneNumber.replace(/\D/g, '') || null : null);
+
+  // WhatsApp needs a valid phone number; otherwise quietly use email
+  const allowedPrefs = ['email', 'whatsapp', 'both'];
+  let pref = allowedPrefs.includes(String(notificationPreference)) ? String(notificationPreference) : 'email';
+  if ((pref === 'whatsapp' || pref === 'both') && !isValidZAPhone(phoneNumber)) pref = 'email';
+
+  const userExists = await prisma.user.findFirst({ where: { OR: [{ email }, ...(phone ? [{ phoneNumber: phone }] : [])] } });
+  if (userExists) fail(409, 'User already exists', undefined, { v1Status: 400 });
+
+  const user = await prisma.user.create({
+    data: { id: uuidv4(), name, email, password: await auth.hashPassword(password), phoneNumber: phone, notificationPreference: pref as 'email' | 'whatsapp' | 'both', updatedAt: new Date() },
+  });
+
+  // POPIA: the sign-up form's (unticked) "news and announcements" box. Recorded either way,
+  // so they aren't asked again at their first login.
+  await require('../utils/privacy').setNewsPreferences(
+    user.id,
+    { email: newsOptIn === true, whatsapp: newsOptIn === true },
+    { source: 'signup', ip: info.ip, answered: true, logAll: true },
+  ).catch((e: any) => console.warn('[signup] news preference not saved:', e?.message || e));
+  // The sign-up form requires ticking "I agree to the Terms of Use and Privacy Policy".
+  await require('../utils/privacyNotice').acceptNotice(user.id, { source: 'signup', ip: info.ip })
+    .catch((e: any) => console.warn('[signup] notice acceptance not saved:', e?.message || e));
+
+  sendWelcomeEmail(user).catch(() => {});
+  return { id: user.id, name: user.name, email: user.email, role: user.role, token: auth.generateToken(user.id, user.role, user.tokenVersion) };
+}
+
+export type LoginResult =
+  | { status: 'signed_in'; session: Session }
+  | { status: 'code_required'; challenge: { challengeId: string; method: string; destination: string | null }; enrolling: boolean };
+
+const MAX_ATTEMPTS = 5;
+const LOCK_TIME = 5 * 60 * 1000;
+
+/**
+ * Checks an email (or phone number) and password. Five wrong passwords lock the account for
+ * five minutes. With 2FA (or when the role needs it), a code is sent instead of a token.
+ */
+export async function logIn(input: { identifier: string; password: string; deviceToken?: string }, info: RequestInfo): Promise<LoginResult> {
+  const rawInput = String(input.identifier || '');
+  // SA local format (0xx) → international (27xx)
+  const normalizedPhone = whatsapp().normalizeZAPhone(rawInput) || rawInput.replace(/\D/g, '');
+  const user = await prisma.user.findFirst({ where: { OR: [{ email: rawInput }, ...(normalizedPhone ? [{ phoneNumber: normalizedPhone }] : [])] } });
+  if (!user) return fail(401, 'User does not exist');
+
+  if (!user.isActive) {
+    // Resend the activation link on each attempt, in case the earlier one expired.
+    await sendActivationLink(user);
+    if (user.email && !user.email.endsWith('@guest.local')) fail(401, 'Your account is not yet active. We\'ve sent you an email with a link to activate your account.');
+    if (user.phoneNumber) fail(401, 'Your account is not yet active. We\'ve sent you a WhatsApp message with a link to activate your account.');
+    fail(401, 'Your account has been deactivated');
+  }
+
+  if (user.lockUntil && user.lockUntil > new Date()) {
+    const minutes = Math.ceil((new Date(user.lockUntil).getTime() - Date.now()) / 60000);
+    fail(429, `Too many attempts. Try again in ${minutes} minute(s).`, undefined, { v1Status: 400 });
+  }
+
+  if (!(await auth.comparePassword(input.password, user.password))) {
+    const attempts = user.failedAttempts + 1;
+    await prisma.user.update({ where: { id: user.id }, data: { failedAttempts: attempts, lockUntil: attempts >= MAX_ATTEMPTS ? new Date(Date.now() + LOCK_TIME) : null } });
+    fail(401, 'Invalid email or password', undefined, { v1Status: 400 });
+  }
+
+  const updated = await prisma.user.update({ where: { id: user.id }, data: { failedAttempts: 0, lockUntil: null }, select: LOGIN_USER_SELECT });
+
+  // Two-factor: the password alone isn't enough unless this browser was remembered earlier.
+  if (updated.twoFactorEnabled && !(await twoFactor.isTrustedDevice(updated.id, input.deviceToken))) {
+    return { status: 'code_required', challenge: await twoFactor.createChallenge(updated, 'login', updated.twoFactorMethod || 'email'), enrolling: false };
+  }
+  // Admins and supervisors must use 2FA. Not set up yet: send a code to the first channel that
+  // can take one; verifying it turns 2FA on. A trusted device can't skip this.
+  if (!updated.twoFactorEnabled && twoFactor.requiresTwoFactor(updated)) {
+    const method = await twoFactor.enforcementMethod(updated);
+    if (method) return { status: 'code_required', challenge: await twoFactor.createChallenge(updated, 'login', method), enrolling: true };
+  }
+  return { status: 'signed_in', session: await completeLogin(updated, info) };
+}
+
+/** The second login step: the emailed or WhatsApp code for a token (and optionally remember this device). */
+export async function verifyLoginCode(input: { challengeId: string; code: string; rememberDevice?: boolean }, info: RequestInfo): Promise<Session> {
+  const challenge = await twoFactor.verifyChallenge(input.challengeId, input.code, 'login');
+  let user = await prisma.user.findUnique({ where: { id: challenge.userId }, select: LOGIN_USER_SELECT });
+  if (!user || !user.isActive) return fail(401, 'Your account has been deactivated');
+
+  // First login since 2FA became required for this role: the code proves the channel works,
+  // so turn 2FA on with it.
+  if (!user.twoFactorEnabled && twoFactor.requiresTwoFactor(user)) {
+    user = await prisma.user.update({ where: { id: user.id }, data: { twoFactorEnabled: true, twoFactorMethod: challenge.method as 'email' | 'whatsapp', updatedAt: new Date() }, select: LOGIN_USER_SELECT });
+    logSecurityEvent({ userId: user.id, type: 'two_factor_enabled', ip: info.ip, userAgent: info.userAgent }).catch(() => {});
+  }
+  const extra = input.rememberDevice === true ? { deviceToken: await twoFactor.issueTrustedDevice(user.id, info.userAgent) } : {};
+  return completeLogin(user, info, extra);
+}
+
+export type ProfileInput = {
+  name?: string; email?: string; phoneNumber?: string | null; notificationPreference?: string; homeCampusId?: string | null;
+  /** A new password; needs currentPassword. */
+  password?: string; currentPassword?: string;
+};
+
+export const PROFILE_SELECT = {
+  id: true, name: true, email: true, role: true, phoneNumber: true, notificationPreference: true, twoFactorEnabled: true,
+  twoFactorMethod: true, createdAt: true, updatedAt: true, isActive: true, homeCampusId: true, tokenVersion: true,
+} as const;
+
+/**
+ * Changes your own details. A new password needs the current one, signs out other devices'
+ * remembered 2FA, and sends a security notice. Returns the account and a fresh token.
+ */
+export async function updateProfile(userId: string, input: ProfileInput, info: RequestInfo) {
+  const user = await prisma.user.findUnique({ where: { id: userId } });
+  if (!user) return fail(404, 'User not found');
+  const { name, email, password, phoneNumber, currentPassword, notificationPreference, homeCampusId } = input;
+
+  // Home campus (only while campuses are on): an active campus, or ''/null for none.
+  let newHomeCampusId = user.homeCampusId;
+  if (homeCampusId !== undefined && await require('../utils/campuses').campusesEnabled()) {
+    if (!homeCampusId) newHomeCampusId = null;
+    else {
+      const campus = await prisma.campus.findFirst({ where: { id: String(homeCampusId), archivedAt: null }, select: { id: true } });
+      if (!campus) fail(400, 'Choose one of the campuses in the list.');
+      newHomeCampusId = campus!.id;
+    }
+  }
+
+  // A password change needs the current password
+  let newHashedPassword: string | undefined;
+  if (typeof password === 'string' && password.trim().length > 0) {
+    const newPw = password.trim();
+    if (!currentPassword) fail(400, 'Current password is required to set a new password');
+    if (!(await auth.comparePassword(currentPassword!, user.password))) fail(400, 'Current password is incorrect');
+    if (newPw.length < 8) fail(400, 'New password must be at least 8 characters long');
+    newHashedPassword = await auth.hashPassword(newPw);
+  }
+
+  const { normalizeZAPhone, isValidZAPhone } = whatsapp();
+  let newPhone = user.phoneNumber;
+  if (phoneNumber !== undefined) newPhone = phoneNumber ? (normalizeZAPhone(phoneNumber) || phoneNumber.replace(/\D/g, '') || null) : null;
+
+  // WhatsApp needs a valid SA phone number
+  const { resolveNotificationPreference } = require('../utils/notificationPreference');
+  const newPref = resolveNotificationPreference(notificationPreference, newPhone, user.notificationPreference);
+  // 2FA codes can't go to WhatsApp without a usable number — move them to email.
+  const newTwoFactorMethod = user.twoFactorMethod === 'whatsapp' && !isValidZAPhone(newPhone) ? 'email' : user.twoFactorMethod;
+
+  const updated = await prisma.user.update({
+    where: { id: userId },
+    data: {
+      name: name || user.name, email: email || user.email, password: newHashedPassword ?? user.password, phoneNumber: newPhone,
+      notificationPreference: newPref, twoFactorMethod: newTwoFactorMethod, homeCampusId: newHomeCampusId, updatedAt: new Date(),
+    },
+    select: PROFILE_SELECT,
+  });
+
+  if (newHashedPassword) {
+    await twoFactor.clearTrustedDevices(updated.id);
+    const { sendMail, buildPasswordChangedEmail } = require('../utils/email');
+    const supportEmail = getSettingSync('org_email', process.env.EMAIL_FROM || '');
+    const content = buildPasswordChangedEmail({ name: updated.name, when: Date.now(), supportEmail });
+    sendMail({ to: updated.email, subject: `Your ${getOrgName()} password was changed`, ...content })
+      .catch((e: any) => console.warn('[email] Failed to send password changed alert:', e?.message || e));
+    const { waText } = require('../utils/notify');
+    waText(updated, content.text).catch(() => {});
+    logSecurityEvent({ userId: updated.id, type: 'password_changed', ip: info.ip, userAgent: info.userAgent }).catch(() => {});
+  }
+
+  return { user: updated, twoFactorRequired: twoFactor.requiresTwoFactor(updated), token: auth.generateToken(updated.id, updated.role, updated.tokenVersion) };
+}
+
+export { ServiceError };

backend/src/services/checkin.ts

@@ -0,0 +1,286 @@
+/**
+ * Checking a ticket in by its QR code (1.51.2). Moved from ticketController.js so
+ * /api/tickets/scan-preview|scan (v1) and /api/v2/checkin/{qrCode} share it.
+ *
+ * Scanning has several normal answers besides "checked in" (already used, wrong event, consent
+ * missing…). They come back as an `outcome`, not thrown, so each caller can show them its way;
+ * only an unknown code is an error (404).
+ */
+import { v4 as uuidv4 } from 'uuid';
+import { prisma } from '../v2/legacy';
+import { fail } from './errors';
+import type { Role } from './registrations';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- the JS helpers below aren't typed yet */
+const transfer = () => require('../utils/ticketTransfer') as { findTransferByOldCode(code: string): Promise<any>; transferredMessage(t: any): string };
+const consent = () => require('../utils/consent') as { consentStatusForTickets(ids: string[]): Promise<Map<string, string>> };
+type Session = { id: string; label?: string | null; startsAt: Date };
+const sessions = () => require('../utils/sessions') as {
+  TIMEZONE: string;
+  eventSchedule(eventId: string): Promise<{ sessions: Session[] } & Record<string, unknown>>;
+  ticketScanSession(schedule: any, list: Session[], pinned: string | null, picked: string | null, now: Date, chosen: string[] | null): { session: Session | null; error: string | null };
+  sessionLabel(session: Session, list: Session[]): string;
+  redeemedForSession(usages: Usage[], sessionId: string): number;
+};
+type Usage = { id?: string; quantityRedeemed: number | null; scannedAt: string; sessionId: string | null };
+
+export type ConsentStatus = 'not_required' | 'given' | 'pending' | 'declined' | 'missing' | string;
+
+/** A ticket that was handed on: the old code tells the scanner who has it now. */
+async function transferredOutcome(qrCode: string) {
+  const t = transfer();
+  const found = await t.findTransferByOldCode(qrCode);
+  return found ? { outcome: 'transferred' as const, message: t.transferredMessage(found) } : null;
+}
+
+export type PreviewResult =
+  | { outcome: 'transferred'; message: string }
+  | {
+    outcome: 'found';
+    ticket: {
+      id: string; quantity: number; isUsed: boolean; eventId: string; consentStatus: ConsentStatus; remaining: number;
+      session: { id: string; label: string } | null; sessionError: string | null;
+      registrationOption: { id: string | null; eventOption: { id: string | null; name: string | null }; variant: { id: string; name: string } | null };
+      event: { id: string; title: string }; user: { id: string; name: string }; attendee: { name: string } | null;
+      usages: Usage[];
+    };
+  };
+
+/** What a scan would do, without checking anything in (the scanner's preview card). */
+export async function previewScan(qrCode: string, opts: { sessionId?: string | null } = {}): Promise<PreviewResult> {
+  // Single JOIN query instead of 6 sequential Prisma round-trips (critical for remote DBs)
+  const rows = await prisma.$queryRaw<any[]>`
+    SELECT
+      t.id, t."qrCode", t.quantity, t."isUsed", t."eventId",
+      ro.id AS "registrationOptionId", ro."sessionId" AS "pinnedSessionId", ro."sessionIds" AS "chosenSessionIds",
+      eo.id AS "eventOptionId", eo.name AS "eventOptionName",
+      ov.id AS "variantId", ov.name AS "variantName",
+      e.id AS "evId", e.title AS "eventTitle", e."scheduleType" AS "scheduleType",
+      u.id AS "userId", u.name AS "userName",
+      a.name AS "attendeeName",
+      COALESCE(
+        json_agg(json_build_object('quantityRedeemed', tu."quantityRedeemed", 'scannedAt', tu."scannedAt", 'sessionId', tu."sessionId"))
+          FILTER (WHERE tu.id IS NOT NULL),
+        '[]'::json
+      ) AS usages
+    FROM "Ticket" t
+    LEFT JOIN "RegistrationOption" ro ON ro.id = t."registrationOptionId"
+    LEFT JOIN "EventOption"        eo ON eo.id = ro."eventOptionId"
+    LEFT JOIN "OptionVariant"      ov ON ov.id = ro."variantId"
+    LEFT JOIN "Event"               e ON  e.id = t."eventId"
+    LEFT JOIN "User"                u ON  u.id = t."userId"
+    LEFT JOIN "Attendee"            a ON  a.id = t."attendeeId"
+    LEFT JOIN "TicketUsage"        tu ON tu."ticketId" = t.id
+    WHERE t."qrCode" = ${qrCode}
+    GROUP BY t.id, ro.id, eo.id, ov.id, e.id, u.id, a.id
+  `;
+  if (!rows || rows.length === 0) return (await transferredOutcome(qrCode)) ?? fail(404, 'Ticket not found');
+
+  const r = rows[0];
+  const consentStatus = (await consent().consentStatusForTickets([r.id])).get(r.id) || 'not_required';
+  const usages: Usage[] = r.usages || [];
+  // Multi-day events: check-in is per session, so what's left is counted for the
+  // session this scan is for (the one picked, or today's).
+  let remaining = Number(r.quantity) - usages.reduce((s, u) => s + (u.quantityRedeemed || 1), 0);
+  let session: { id: string; label: string } | null = null;
+  let sessionError: string | null = null;
+  if (r.scheduleType === 'sessions') {
+    const s = sessions();
+    const schedule = await s.eventSchedule(r.eventId);
+    const found = s.ticketScanSession(schedule, schedule.sessions, r.pinnedSessionId, opts.sessionId || null, new Date(), r.chosenSessionIds);
+    sessionError = found.error;
+    if (found.session) {
+      session = { id: found.session.id, label: s.sessionLabel(found.session, schedule.sessions) };
+      remaining = Number(r.quantity) - s.redeemedForSession(usages, found.session.id);
+    } else {
+      remaining = 0;
+    }
+  }
+  return {
+    outcome: 'found',
+    ticket: {
+      id: r.id, quantity: Number(r.quantity), isUsed: r.isUsed, eventId: r.eventId, consentStatus, remaining, session, sessionError,
+      registrationOption: {
+        id: r.registrationOptionId,
+        eventOption: { id: r.eventOptionId, name: r.eventOptionName },
+        variant: r.variantId ? { id: r.variantId, name: r.variantName } : null,
+      },
+      event: { id: r.evId, title: r.eventTitle },
+      user: { id: r.userId, name: r.userName },
+      attendee: r.attendeeName ? { name: r.attendeeName } : null,
+      usages,
+    },
+  };
+}
+
+export type ScanTicket = {
+  id: string; quantity: number; isUsed: boolean; eventId: string; event: { title: string };
+  registrationOption: { eventOption: { id: string | null; name: string | null; isMainTicket: boolean | null } };
+  usages: Usage[];
+};
+
+export type ScanOptions = {
+  /** Refuse a ticket for any other event (the scanner's chosen event). */
+  eventId?: string | null;
+  /** Only tickets valid for this section. */
+  sectionId?: string | null;
+  /** Multi-day events: the session (default: today's). */
+  sessionId?: string | null;
+  /** The scanning device, so its own offline lock doesn't block it. */
+  deviceId?: string | null;
+  /** How many people to check in (default: everyone left). */
+  qty?: number | null;
+  /** Supervisors and admins: check in without parental consent (logged). */
+  overrideConsent?: boolean;
+};
+
+export type ScanResult =
+  | { outcome: 'checked_in'; message: string; session: { id: string; label: string } | null; ticketUsage: { id: string; scannedAt: Date; quantityRedeemed: number; sessionId: string | null }; ticket: ScanTicket; qtyRedeemed: number; totalRedeemed: number; remaining: number }
+  | { outcome: 'transferred'; message: string }
+  | { outcome: 'wrong_event' | 'section_not_found' | 'wrong_section' | 'no_session'; message: string; ticket: ScanTicket }
+  | { outcome: 'locked'; message: string }
+  | { outcome: 'already_used'; message: string; ticket: ScanTicket }
+  | { outcome: 'consent_required'; message: string; consentStatus: ConsentStatus; canOverride: boolean; ticket: ScanTicket };
+
+/** Checks a ticket in (all of it, or `qty` people), or says why it can't be. */
+export async function scanTicket(qrCode: string, actor: { id: string; role: Role }, opts: ScanOptions = {}, ip?: string): Promise<ScanResult> {
+  // Single JOIN query — avoids multiple sequential round-trips to the remote DB
+  const rows = await prisma.$queryRaw<any[]>`
+    SELECT
+      t.id, t.quantity, t."isUsed", t."eventId",
+      e.title AS "eventTitle", e."scheduleType" AS "scheduleType",
+      ro."sessionId" AS "pinnedSessionId", ro."sessionIds" AS "chosenSessionIds",
+      eo.id AS "eventOptionId", eo.name AS "eventOptionName", eo."isMainTicket" AS "isMainTicket",
+      COALESCE(
+        json_agg(json_build_object('id', tu.id, 'quantityRedeemed', tu."quantityRedeemed", 'scannedAt', tu."scannedAt", 'sessionId', tu."sessionId"))
+          FILTER (WHERE tu.id IS NOT NULL),
+        '[]'::json
+      ) AS usages
+    FROM "Ticket" t
+    LEFT JOIN "Event"              e  ON  e.id = t."eventId"
+    LEFT JOIN "RegistrationOption" ro ON ro.id = t."registrationOptionId"
+    LEFT JOIN "EventOption"        eo ON eo.id = ro."eventOptionId"
+    LEFT JOIN "TicketUsage"        tu ON tu."ticketId" = t.id
+    WHERE t."qrCode" = ${qrCode}
+    GROUP BY t.id, e.id, eo.id, ro.id
+  `;
+  if (!rows || rows.length === 0) return (await transferredOutcome(qrCode)) ?? fail(404, 'Ticket not found');
+
+  const r = rows[0];
+  const ticket: ScanTicket = {
+    id: r.id,
+    quantity: Number(r.quantity),
+    isUsed: r.isUsed,
+    eventId: r.eventId,
+    event: { title: r.eventTitle },
+    registrationOption: { eventOption: { id: r.eventOptionId, name: r.eventOptionName, isMainTicket: r.isMainTicket } },
+    usages: r.usages || [],
+  };
+
+  // Ensure the ticket belongs to the event being scanned, when given
+  const providedEventId = String(opts.eventId || '').trim();
+  if (providedEventId && ticket.eventId !== providedEventId) return { outcome: 'wrong_event', message: 'Ticket belongs to a different event', ticket };
+
+  // Section checks used to happen only in the browser; enforce them here too.
+  const sectionId = String(opts.sectionId || '').trim() || null;
+  if (sectionId) {
+    const section = await prisma.section.findUnique({ where: { id: sectionId }, include: { allowedOptions: true } });
+    if (!section || section.eventId !== ticket.eventId) return { outcome: 'section_not_found', message: 'Section not found for this event', ticket };
+    if (!section.allowedOptions.some(o => o.eventOptionId === r.eventOptionId)) return { outcome: 'wrong_section', message: 'This ticket is not valid for this section', ticket };
+  }
+
+  // A section (or the whole event) locked to another device for offline scanning
+  // can't be scanned online — those scans would be invisible to the offline device.
+  const { blockingLock } = require('../utils/scanLocks') as { blockingLock(target: object, opts: object): Promise<any> };
+  const lock = await blockingLock({ eventId: ticket.eventId, optionId: r.eventOptionId }, { sectionId, deviceId: opts.deviceId || null });
+  if (lock) {
+    const scope = lock.section ? `"${lock.section.name}"` : 'This event';
+    return { outcome: 'locked', message: `${scope} is offline-locked by ${lock.user?.name || 'another device'}${lock.deviceName ? ` on ${lock.deviceName}` : ''}. Scan it on that device, or ask a supervisor to release the lock.` };
+  }
+
+  // Multi-day events: the check-in is for one session (the one picked, or today's), and
+  // what's left is counted per session.
+  let session: Session | null = null;
+  let schedule: { sessions: Session[] } | null = null;
+  const s = sessions();
+  if (r.scheduleType === 'sessions') {
+    schedule = await s.eventSchedule(ticket.eventId);
+    const found = s.ticketScanSession(schedule, schedule.sessions, r.pinnedSessionId, String(opts.sessionId || '').trim() || null, new Date(), r.chosenSessionIds);
+    if (!found.session) return { outcome: 'no_session', message: found.error || 'No session is open for check-in now', ticket };
+    session = found.session;
+  }
+  const label = session && schedule ? s.sessionLabel(session, schedule.sessions) : '';
+
+  const totalRedeemed = session
+    ? s.redeemedForSession(ticket.usages, session.id)
+    : ticket.usages.reduce((sum, u) => sum + (u.quantityRedeemed || 1), 0);
+  const remaining = (ticket.quantity || 1) - totalRedeemed;
+
+  if (remaining <= 0) {
+    if (session) {
+      const last = ticket.usages.filter(u => u.sessionId === session!.id).sort((a, b) => +new Date(b.scannedAt) - +new Date(a.scannedAt))[0];
+      const at = last ? new Date(last.scannedAt).toLocaleTimeString('en-ZA', { timeZone: s.TIMEZONE, hour: '2-digit', minute: '2-digit' }) : '';
+      return { outcome: 'already_used', message: `Already checked in for ${label}${at ? ` at ${at}` : ''}`, ticket };
+    }
+    return { outcome: 'already_used', message: 'Ticket has already been fully used', ticket };
+  }
+
+  // Youth events: no check-in without parental consent, unless a supervisor overrides.
+  const consentStatus = (await consent().consentStatusForTickets([ticket.id])).get(ticket.id) || 'not_required';
+  if (!['not_required', 'given'].includes(consentStatus)) {
+    const canOverride = ['admin', 'supervisor'].includes(actor.role);
+    if (!(opts.overrideConsent === true && canOverride)) {
+      const why = consentStatus === 'declined' ? 'Parental consent was declined' : consentStatus === 'pending' ? 'Parental consent is still pending' : 'Parental consent is missing';
+      return { outcome: 'consent_required', message: `${why} — this ticket can't be checked in.`, consentStatus, canOverride, ticket };
+    }
+    const { logAdminAction } = require('../utils/adminAudit') as { logAdminAction(entry: object): Promise<void> };
+    logAdminAction({ actorId: actor.id, actorRole: actor.role, action: 'consent_override', targetType: 'Ticket', targetId: ticket.id, metadata: { consentStatus, eventId: ticket.eventId }, ip });
+  }
+
+  // How many to check in this scan (defaults to all remaining)
+  const requestedQty = Math.trunc(Number(opts.qty)) || remaining;
+  const qtyToRedeem = Math.min(Math.max(1, requestedQty), remaining);
+  const newTotalRedeemed = totalRedeemed + qtyToRedeem;
+  const newRemaining = (ticket.quantity || 1) - newTotalRedeemed;
+
+  // The usage insert and the ticket's status don't depend on each other
+  const [ticketUsage] = await Promise.all([
+    prisma.ticketUsage.create({
+      data: { id: uuidv4(), ticketId: ticket.id, scannedById: actor.id, quantityRedeemed: qtyToRedeem, sessionId: session ? session.id : null },
+    }),
+    // A multi-session ticket is never "used up" — it's checked in again next session.
+    prisma.ticket.update({ where: { id: ticket.id }, data: { isUsed: session ? false : newRemaining <= 0, updatedAt: new Date() } }),
+  ]);
+
+  // Only Main Tickets trigger a check-in notification
+  if (ticket.registrationOption.eventOption.isMainTicket) {
+    (require('../utils/notifications') as { sendCheckInEmails(id: string, qty: number, total: number, left: number): Promise<unknown> })
+      .sendCheckInEmails(ticket.id, qtyToRedeem, newTotalRedeemed, newRemaining)
+      .catch(e => console.error('Failed to send check-in notification:', e));
+  }
+
+  return {
+    outcome: 'checked_in',
+    message: `Ticket scanned successfully${session ? ` for ${label}` : ''} (${qtyToRedeem} of ${ticket.quantity || 1} redeemed${newRemaining > 0 ? `, ${newRemaining} remaining` : ''})`,
+    session: session ? { id: session.id, label } : null,
+    ticketUsage,
+    ticket,
+    qtyRedeemed: qtyToRedeem,
+    totalRedeemed: newTotalRedeemed,
+    remaining: newRemaining,
+  };
+}
+
+/** The HTTP status and body v1 (/api/tickets/scan/:qrCode) has always answered for each outcome. */
+export function v1ScanResponse(result: ScanResult): { status: number; body: Record<string, unknown> } {
+  const { outcome, ...rest } = result;
+  switch (outcome) {
+    case 'checked_in': return { status: 200, body: rest };
+    case 'transferred': return { status: 410, body: { ...rest, code: 'TICKET_TRANSFERRED' } };
+    case 'locked': return { status: 423, body: { ...rest, code: 'SCAN_LOCKED' } };
+    case 'no_session': return { status: 400, body: { ...rest, code: 'NO_SESSION' } };
+    case 'already_used': return { status: 403, body: { ...rest, remaining: 0 } };
+    case 'consent_required': return { status: 403, body: { ...rest, code: 'CONSENT_REQUIRED' } };
+    default: return { status: 400, body: rest };
+  }
+}

backend/src/services/errors.ts

@@ -0,0 +1,26 @@
+/**
+ * An error from a service (src/services/*) with the HTTP status it means. v2 turns it into its
+ * error shape by the status (v2/errors.ts); v1 controllers keep answering as they always did —
+ * `v1Status` when v1 used a different status for it (e.g. 400 for a wrong password).
+ */
+export class ServiceError extends Error {
+  readonly statusCode: number;
+  /** Extra, e.g. a code the caller can switch on. */
+  readonly code?: string;
+  readonly v1Status?: number;
+
+  constructor(statusCode: number, message: string, code?: string, opts: { v1Status?: number } = {}) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.v1Status = opts.v1Status;
+  }
+}
+
+export const fail = (statusCode: number, message: string, code?: string, opts?: { v1Status?: number }): never => {
+  throw new ServiceError(statusCode, message, code, opts);
+};
+
+/** The status a v1 controller answers for an error (its old one where it differs). */
+export const v1StatusOf = (error: { v1Status?: number; statusCode?: number } | null | undefined, fallback: number): number =>
+  error?.v1Status || error?.statusCode || fallback;

backend/src/services/eventDetails.ts

@@ -0,0 +1,373 @@
+/**
+ * One event in full, its ticket options and variants, attachments, calendar file and short link
+ * (1.51.8). Moved from eventController.js so /api/events/* (v1) and /api/v2/events/* share it.
+ * The pre-migration fallbacks (attachments kept in JSON manifests on disk, clients without the
+ * tier/variant models) are gone: every install has those tables.
+ */
+import fs from 'fs';
+import path from 'path';
+import { v4 as uuidv4 } from 'uuid';
+import { prisma } from '../v2/legacy';
+import { fail } from './errors';
+import { SESSIONS_INCLUDE, SERIES_SELECT, withSchedule } from './events';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- the JS helpers below aren't typed yet */
+const sessionsUtil = require('../utils/sessions') as {
+  isPickOption(event: any, option: any): boolean;
+  activeSessions(sessions: any[]): Array<{ id: string }>;
+  sessionBookings(eventId: string): Promise<Map<string, number>>;
+  forgetSchedule(eventId: string): void;
+};
+const { publicOptions } = require('../utils/volunteers') as { publicOptions<O extends { id: string }>(event: any): O[] };
+const { EVENT_CAMPUS_SELECT } = require('../utils/campuses') as { EVENT_CAMPUS_SELECT: Record<string, true> };
+const { assertEventOpen } = require('../utils/cashupUtils') as { assertEventOpen(eventId: string): Promise<unknown> };
+const { takenCount } = require('../utils/stock') as { takenCount(where: object): Promise<number> };
+
+/** Where uploaded attachments live (served at /uploads/event-files/…). */
+export const ATTACHMENTS_DIR = path.join(__dirname, '..', '..', 'public', 'uploads', 'event-files');
+export const ALLOWED_DOCS = ['.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx', '.txt', '.csv', '.zip'];
+
+/** A stored path as an absolute URL (the caller knows the host the request came to). */
+export type UrlOf = (stored: string | null | undefined) => string | null;
+
+/**
+ * Who's looking: staff of a campus they may see get everything (inactive and not-yet-live
+ * events, who created it, who gets its emails, the kids/volunteer tickets); everyone else gets
+ * the public view and NOT_FOUND for events that aren't public.
+ */
+export type Viewer = { staff: boolean; scope: object | null };
+
+const { canView } = require('../utils/campusScope') as { canView(scope: object | null, campusId: string | null): boolean };
+/** Staff see an event in full when it's at a campus they work with (or campuses are off for them). */
+const staffViewOf = (viewer: Viewer, campusId: string | null) => viewer.staff && canView(viewer.scope, campusId);
+
+const notPublic = (ev: { isActive: boolean | null; goLiveAt: Date | null }) =>
+  ev.isActive === false || (ev.goLiveAt != null && new Date() < new Date(ev.goLiveAt));
+
+/**
+ * One event in full: ticket options with what's left (per variant, and per session for
+ * "pick sessions" tickets), sessions with bookings, the attendee form, attachments, bundle deals
+ * on sale and the next event in its series.
+ */
+export async function getEventDetail(eventId: string, viewer: Viewer, urlOf: UrlOf) {
+  const event: any = await prisma.event.findUnique({
+    where: { id: eventId },
+    include: {
+      // (createdBy and notifyRecipients are dropped again below for the public view)
+      eventOptions: { include: { earlyBirdTiers: true, variants: { orderBy: { order: 'asc' } } } },
+      sessions: SESSIONS_INCLUDE,
+      campus: { select: EVENT_CAMPUS_SELECT },
+      series: SERIES_SELECT,
+      attachments: true,
+      ...(viewer.staff ? {
+        createdBy: { select: { id: true, name: true, email: true } },
+        notifyRecipients: { select: { id: true, name: true, email: true, role: true } },
+      } : {}),
+    },
+  });
+  if (!event) return fail(404, 'Event not found');
+  if (!staffViewOf(viewer, event.campusId)) {
+    // Campus-scoped staff get the public view of other campuses' events.
+    delete event.createdBy;
+    delete event.notifyRecipients;
+    if (notPublic(event)) fail(404, 'Event not found');
+    // The kids check-in and volunteer tickets are handed out by staff, never sold.
+    event.eventOptions = publicOptions(event);
+  }
+
+  const f = await prisma.eventForm.findUnique({ where: { eventId }, include: { fields: true } });
+  const form = f ? {
+    id: f.id,
+    isRequired: !!f.isRequired,
+    fields: [...f.fields].sort((a, b) => (a.order || 0) - (b.order || 0)).map(fl => ({
+      id: fl.id, type: fl.type, label: fl.label, isRequired: !!fl.isRequired, order: fl.order || 0, helpText: fl.helpText || null, options: fl.options || null,
+    })),
+  } : null;
+
+  // What's left per option and variant (taken = non-cancelled registrations + places held for
+  // live waitlist offers). "Pick sessions" tickets have places per session instead.
+  const eventOptions = await Promise.all((event.eventOptions || []).map(async (opt: any) => {
+    if (sessionsUtil.isPickOption(event, opt)) {
+      const sessionAvailability: Record<string, number> = {};
+      if (opt.stockLimit > 0) {
+        for (const s of sessionsUtil.activeSessions(event.sessions)) {
+          sessionAvailability[s.id] = Math.max(0, opt.stockLimit - await takenCount({ eventOptionId: opt.id, sessionId: s.id }));
+        }
+      }
+      return { ...opt, soldCount: 0, availableCount: null, sessionAvailability };
+    }
+    const soldCount = await takenCount({ eventOptionId: opt.id });
+    const variants = await Promise.all((opt.variants || []).map(async (v: any) => {
+      if (!v.stockLimit) return { ...v, soldCount: 0, availableCount: null };
+      const vSold = await takenCount({ eventOptionId: opt.id, variantId: v.id });
+      return { ...v, soldCount: vSold, availableCount: Math.max(0, v.stockLimit - vSold) };
+    }));
+    return { ...opt, soldCount, availableCount: opt.stockLimit > 0 ? Math.max(0, opt.stockLimit - soldCount) : null, variants };
+  }));
+
+  const bookings = event.scheduleType === 'sessions' ? await sessionsUtil.sessionBookings(eventId).catch(() => null) : null;
+  const { publicBundlesForEvent } = require('../controllers/bundleController') as { publicBundlesForEvent(id: string): Promise<unknown[]> };
+  const { nextInSeries } = require('../utils/series') as { nextInSeries(ev: unknown): Promise<unknown> };
+  return withSchedule({
+    ...event,
+    eventOptions,
+    picture: urlOf(event.picture),
+    attachments: (event.attachments || []).map((att: any) => ({ ...att, url: urlOf(att.url) })),
+    form,
+    bundles: await publicBundlesForEvent(eventId).catch(() => []),
+    nextInSeries: await nextInSeries(event).catch(() => null),
+  }, bookings);
+}
+
+/** The event (or each session of a multi-day event) as an .ics calendar file. */
+export async function eventCalendar(eventId: string, viewer: Viewer): Promise<{ filename: string; ics: string }> {
+  const event = await prisma.event.findUnique({
+    where: { id: eventId },
+    select: { id: true, title: true, description: true, startDate: true, endDate: true, location: true, isActive: true, goLiveAt: true, scheduleType: true, campusId: true, sessions: { orderBy: { startsAt: 'asc' } } },
+  });
+  if (!event || (!staffViewOf(viewer, event.campusId) && notPublic(event))) return fail(404, 'Event not found');
+  const { buildEventIcs } = require('../utils/icsUtils') as { buildEventIcs(ev: unknown, url: string): string };
+  let frontendUrl = (process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');
+  // The ics library's URL check needs a scheme.
+  if (!/^[a-z0-9+.-]+:\/\//i.test(frontendUrl)) frontendUrl = `https://${frontendUrl}`;
+  return {
+    filename: `${event.title.replace(/[^a-z0-9 -]/gi, '').slice(0, 60) || 'event'}.ics`,
+    ics: buildEventIcs(event, `${frontendUrl}/events/${event.id}`),
+  };
+}
+
+const VALID_ALIAS = /^[a-zA-Z0-9_-]{1,100}$/;
+
+/** An active event by its short link (`/camp2026`), any letter case. */
+export async function eventByAlias(alias: string) {
+  if (!VALID_ALIAS.test(alias)) return fail(404, 'Event not found');
+  const event = await prisma.event.findFirst({
+    where: { redirectUrl: { equals: alias, mode: 'insensitive' }, isActive: true },
+    select: { id: true, title: true, description: true, startDate: true, endDate: true, registrationDeadline: true, goLiveAt: true, price: true, picture: true, isActive: true, redirectUrl: true },
+  });
+  if (!event) return fail(404, 'Event not found or inactive');
+  const now = new Date();
+  const isLive = (!event.startDate || new Date(event.startDate) >= now) && (!event.endDate || new Date(event.endDate) >= now);
+  return { ...event, isLive };
+}
+
+// ─── Ticket options and variants ─────────────────────────────────────────────
+
+/** A staff price: undefined keeps `current`, '' or null clears it. */
+export function parseStaffPrice(value: unknown, current: number | null = null): number | null {
+  if (value === undefined) return current;
+  if (value === null || value === '') return null;
+  const n = parseFloat(String(value));
+  if (!(n >= 0)) fail(400, 'Staff price must be zero or more');
+  return n;
+}
+
+const openEvent = async (eventId: string) => {
+  try {
+    await assertEventOpen(eventId);
+  } catch (e: any) {
+    fail(e.message === 'Event not found' ? 404 : 400, e.message);
+  }
+};
+
+export type OptionInput = {
+  name?: string; price?: number | string; isMainTicket?: boolean; stockLimit?: number | string; staffPrice?: number | string | null;
+  sessionMode?: string; earlyBirdTiers?: any[]; variants?: any[];
+};
+
+export async function createOption(eventId: string, input: OptionInput) {
+  const event = await prisma.event.findUnique({ where: { id: eventId }, select: { id: true } });
+  if (!event) return fail(404, 'Event not found');
+  await openEvent(eventId);
+  if (!input.name) fail(400, 'Give the ticket a name');
+  const option = await prisma.eventOption.create({
+    data: {
+      id: uuidv4(), eventId, name: String(input.name), price: parseFloat(String(input.price ?? 0)) || 0, isMainTicket: input.isMainTicket || false,
+      stockLimit: input.stockLimit ? parseInt(String(input.stockLimit), 10) : 0, staffPrice: parseStaffPrice(input.staffPrice),
+      sessionMode: input.sessionMode === 'pick' ? 'pick' : 'all',
+    },
+  });
+  sessionsUtil.forgetSchedule(eventId);
+  return option;
+}
+
+/**
+ * Changes a ticket option, and — when sent — its early-bird tiers and variants. Tiers and
+ * variants are upserted by id, so purchases keep pointing at the tier they were bought under;
+ * ones left out are removed only when nothing was bought under them.
+ */
+export async function updateOption(optionId: string, input: OptionInput) {
+  const existing = await prisma.eventOption.findUnique({ where: { id: optionId } });
+  if (!existing) return fail(404, 'Event option not found');
+  await openEvent(existing.eventId);
+  const updated = await prisma.eventOption.update({
+    where: { id: optionId },
+    data: {
+      name: input.name !== undefined ? String(input.name) : existing.name,
+      price: input.price !== undefined ? parseFloat(String(input.price)) : existing.price,
+      isMainTicket: input.isMainTicket !== undefined ? input.isMainTicket : existing.isMainTicket,
+      stockLimit: input.stockLimit !== undefined ? parseInt(String(input.stockLimit), 10) : existing.stockLimit,
+      staffPrice: parseStaffPrice(input.staffPrice, existing.staffPrice),
+      sessionMode: input.sessionMode !== undefined ? (input.sessionMode === 'pick' ? 'pick' : 'all') : existing.sessionMode,
+    },
+  });
+
+  // Early-bird tiers: deleting and recreating them would give every tier a new id and cut past
+  // purchases off from the tier they were bought under (and reset its stock count).
+  if (Array.isArray(input.earlyBirdTiers)) {
+    const incoming = input.earlyBirdTiers.filter(t => t && t.id).map(t => t.id);
+    for (const et of await prisma.earlyBirdTier.findMany({ where: { eventOptionId: optionId } })) {
+      if (incoming.includes(et.id)) continue;
+      // Never delete a tier still attributed on past purchases.
+      if (await prisma.registrationOptionTranche.count({ where: { appliedTierId: et.id } }) === 0) {
+        await prisma.earlyBirdTier.delete({ where: { id: et.id } }).catch(() => {});
+      }
+    }
+    for (let i = 0; i < input.earlyBirdTiers.length; i++) {
+      const t = input.earlyBirdTiers[i];
+      if (!t || !t.deadline || t.price === undefined || t.price === null) continue;
+      const deadline = new Date(t.deadline);
+      const p = parseFloat(t.price);
+      if (isNaN(deadline.getTime()) || !(p >= 0)) continue;
+      const data = { eventOptionId: optionId, variantId: t.variantId || null, deadline, price: p, order: typeof t.order === 'number' ? t.order : i, stockLimit: t.stockLimit ? parseInt(t.stockLimit, 10) : 0 };
+      if (t.id) await prisma.earlyBirdTier.upsert({ where: { id: t.id }, update: data, create: { id: t.id, ...data } });
+      else await prisma.earlyBirdTier.create({ data: { id: uuidv4(), ...data } });
+    }
+  }
+
+  // Variants: upserted by id; ones left out are deleted only when nobody has bought them.
+  if (Array.isArray(input.variants)) {
+    const incoming = input.variants.filter(v => v.id).map(v => v.id);
+    for (const ov of await prisma.optionVariant.findMany({ where: { eventOptionId: optionId } })) {
+      if (!incoming.includes(ov.id) && await prisma.registrationOption.count({ where: { variantId: ov.id } }) === 0) {
+        await prisma.optionVariant.delete({ where: { id: ov.id } });
+      }
+    }
+    for (let i = 0; i < input.variants.length; i++) {
+      const v = input.variants[i];
+      if (!v.name) continue;
+      const data = {
+        name: v.name,
+        price: v.price !== undefined && v.price !== null && v.price !== '' ? parseFloat(v.price) : null,
+        stockLimit: v.stockLimit !== undefined ? parseInt(v.stockLimit, 10) : 0,
+        staffPrice: parseStaffPrice(v.staffPrice),
+        order: i,
+      };
+      if (v.id) await prisma.optionVariant.update({ where: { id: v.id }, data });
+      else await prisma.optionVariant.create({ data: { id: uuidv4(), eventOptionId: optionId, ...data } });
+    }
+  }
+
+  if (input.stockLimit !== undefined || input.variants !== undefined) {
+    (require('../utils/waitlist') as { queueWaitlist(eventId: string): void }).queueWaitlist(existing.eventId);
+  }
+  return prisma.eventOption.findUniqueOrThrow({ where: { id: updated.id }, include: { earlyBirdTiers: true, variants: { orderBy: { order: 'asc' } } } });
+}
+
+/** Removes a ticket option nobody has bought (and never the event's only main ticket). */
+export async function deleteOption(optionId: string) {
+  const option = await prisma.eventOption.findUnique({ where: { id: optionId } });
+  if (!option) return fail(404, 'Event option not found');
+  await openEvent(option.eventId);
+  if (option.isMainTicket) {
+    const others = await prisma.eventOption.count({ where: { eventId: option.eventId, isMainTicket: true, NOT: { id: option.id } } });
+    if (others === 0) fail(400, 'Cannot delete the only main ticket option');
+  }
+  if (await prisma.registrationOption.count({ where: { eventOptionId: optionId } }) > 0) fail(400, 'Cannot delete event option that has registrations');
+  await prisma.eventOption.delete({ where: { id: optionId } });
+}
+
+export type VariantInput = { name?: string; price?: number | string | null; stockLimit?: number | string; order?: number | string; staffPrice?: number | string | null };
+
+export async function createVariant(optionId: string, input: VariantInput) {
+  const option = await prisma.eventOption.findUnique({ where: { id: optionId } });
+  if (!option) return fail(404, 'Event option not found');
+  await openEvent(option.eventId);
+  if (!input.name) fail(400, 'Variant name is required');
+  return prisma.optionVariant.create({
+    data: {
+      id: uuidv4(), eventOptionId: optionId, name: String(input.name),
+      price: input.price !== undefined && input.price !== null && input.price !== '' ? parseFloat(String(input.price)) : null,
+      stockLimit: input.stockLimit ? parseInt(String(input.stockLimit), 10) : 0,
+      staffPrice: parseStaffPrice(input.staffPrice),
+      order: input.order !== undefined ? parseInt(String(input.order), 10) : 0,
+    },
+  });
+}
+
+export async function updateVariant(variantId: string, input: VariantInput) {
+  const variant = await prisma.optionVariant.findUnique({ where: { id: variantId }, include: { eventOption: { select: { eventId: true } } } });
+  if (!variant) return fail(404, 'Variant not found');
+  await openEvent(variant.eventOption.eventId);
+  return prisma.optionVariant.update({
+    where: { id: variantId },
+    data: {
+      name: input.name !== undefined ? String(input.name) : variant.name,
+      staffPrice: parseStaffPrice(input.staffPrice, variant.staffPrice),
+      price: input.price !== undefined ? (input.price === null || input.price === '' ? null : parseFloat(String(input.price))) : variant.price,
+      stockLimit: input.stockLimit !== undefined ? parseInt(String(input.stockLimit), 10) : variant.stockLimit,
+      order: input.order !== undefined ? parseInt(String(input.order), 10) : variant.order,
+    },
+  });
+}
+
+/** Removes a variant nobody has bought. */
+export async function deleteVariant(variantId: string) {
+  const variant = await prisma.optionVariant.findUnique({ where: { id: variantId }, include: { eventOption: { select: { eventId: true } } } });
+  if (!variant) return fail(404, 'Variant not found');
+  await openEvent(variant.eventOption.eventId);
+  if (await prisma.registrationOption.count({ where: { variantId } }) > 0) fail(400, 'Cannot delete variant with existing registrations');
+  await prisma.optionVariant.delete({ where: { id: variantId } });
+}
+
+// ─── Attachments ─────────────────────────────────────────────────────────────
+
+export async function listAttachments(eventId: string, urlOf: UrlOf) {
+  const items = await prisma.eventAttachment.findMany({ where: { eventId }, orderBy: { createdAt: 'desc' } });
+  return items.map(att => ({ ...att, url: urlOf(att.url) }));
+}
+
+/** Records a file multer has already saved in ATTACHMENTS_DIR. */
+export async function recordAttachment(eventId: string, file: { originalname: string; filename: string; mimetype: string; size: number }, urlOf: UrlOf) {
+  const event = await prisma.event.findUnique({ where: { id: eventId }, select: { id: true } });
+  if (!event) {
+    fs.promises.unlink(path.join(ATTACHMENTS_DIR, file.filename)).catch(() => {});
+    return fail(404, 'Event not found');
+  }
+  const created = await prisma.eventAttachment.create({
+    data: { id: uuidv4(), eventId, originalName: file.originalname, filename: file.filename, mimeType: file.mimetype, size: file.size, url: `/uploads/event-files/${file.filename}` },
+  });
+  return { ...created, url: urlOf(created.url) };
+}
+
+export async function deleteAttachment(eventId: string, attachmentId: string) {
+  const att = await prisma.eventAttachment.findUnique({ where: { id: attachmentId } });
+  if (!att || att.eventId !== eventId) return fail(404, 'Attachment not found');
+  // The file goes too (best effort; the record is what the site shows).
+  await fs.promises.unlink(path.join(ATTACHMENTS_DIR, att.filename)).catch(() => {});
+  await prisma.eventAttachment.delete({ where: { id: attachmentId } });
+}
+
+/** Admin diagnostics: whether the attachments table answers, and which database it is (no secrets). */
+export async function attachmentsStatus() {
+  let tableQueryable = false;
+  let probeError: string | null = null;
+  try {
+    await prisma.eventAttachment.findFirst({});
+    tableQueryable = true;
+  } catch (e: any) {
+    probeError = String(e?.message || e);
+  }
+  let database: Record<string, string | undefined> | null = null;
+  try {
+    const u = new URL(process.env.DATABASE_URL || '');
+    database = { protocol: u.protocol.replace(':', ''), host: u.hostname, port: u.port || undefined, database: u.pathname.replace(/^\//, '') || undefined };
+  } catch { /* not a URL */ }
+  return { prismaClientHasEventAttachmentModel: true, databaseTableQueryable: tableQueryable, probeError, database };
+}
+
+/** Imports attachments still listed in old JSON manifests on disk into the database. */
+export async function syncAttachmentManifests(opts: { dryRun: boolean; remove: boolean }) {
+  const { syncManifestsToDb } = require('../utils/attachmentsSync') as { syncManifestsToDb(db: unknown, o: { dryRun: boolean; removeManifestAfterImport: boolean }): Promise<Record<string, unknown>> };
+  return { ...opts, ...(await syncManifestsToDb(prisma, { dryRun: opts.dryRun, removeManifestAfterImport: opts.remove })) };
+}

backend/src/services/events.ts

@@ -0,0 +1,411 @@
+/**
+ * Setting events up (1.51.7): create, edit, deactivate, the staff list, notification recipients
+ * and copying set-up from another event. Moved from eventController.js so /api/events (v1) and
+ * /api/v2/events share it.
+ */
+import { v4 as uuidv4 } from 'uuid';
+import type { Prisma } from '@prisma/client';
+import { prisma } from '../v2/legacy';
+import { fail, ServiceError } from './errors';
+import type { Role } from './registrations';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- the JS helpers below aren't typed yet */
+type CampusScope = object | null;
+const sessionsUtil = require('../utils/sessions') as {
+  sessionError(message: string): Error;
+  normalizeReminders(v: unknown): unknown;
+  normalizeCertificateConfig(v: unknown): unknown;
+  normalizeSessionsInput(v: unknown): Array<{ cancelled?: boolean } & Record<string, unknown>>;
+  scheduleBounds(sessions: unknown[]): { startDate: Date; endDate: Date };
+  forgetSchedule(eventId: string): void;
+  syncEventSessions(tx: any, eventId: string, sessions: unknown[]): Promise<{ sessions: Array<{ id: string; order: number; cancelledAt: Date | null }>; changes: Record<string, number> }>;
+  activeSessions(sessions: any[]): any[];
+  registrationClosesAt(ev: any, sessions: any[]): Date;
+  wholeCourseClosesAt(ev: any, sessions: any[]): Date;
+  lateInfo(ev: any, sessions: any[], now: Date): unknown;
+};
+const campuses = require('../utils/campuses') as {
+  campusesEnabled(): Promise<boolean>;
+  campusForEvent(campusId: unknown, opts: { enabled: boolean; currentCampusId?: string | null }): Promise<{ campusId?: string | null; error?: string }>;
+  campusWhere(filter: string, opts: { enabled: boolean; withAllCampuses?: boolean }): object;
+  resolveCampusFilter(value: unknown): Promise<string>;
+  EVENT_CAMPUS_SELECT: Record<string, true>;
+};
+const campusScope = require('../utils/campusScope') as {
+  canManage(scope: object, campusId: string | null): boolean;
+  eventWhere(scope: CampusScope): object;
+  withScope(where: object, scopeWhere: object): object;
+};
+const seriesUtil = require('../utils/series') as { seriesForEvent(seriesId: unknown): Promise<string | null | undefined> };
+const { assertEventOpen } = require('../utils/cashupUtils') as { assertEventOpen(eventId: string): Promise<unknown> };
+const { logAdminAction } = require('../utils/adminAudit') as { logAdminAction(entry: object): Promise<void> };
+
+export type Actor = { id: string; role: Role };
+/** The caller's campus scope (utils/campusScope.scopeFor) and IP, for checks and the audit log. */
+export type Ctx = { scope: CampusScope; ip?: string };
+/** An event body as the event wizard sends it (v1 and v2 take the same fields). */
+export type EventInput = Record<string, any>;
+
+export const SERIES_SELECT = { select: { id: true, name: true, slug: true } } as const;
+export const SESSIONS_INCLUDE = { orderBy: { startsAt: 'asc' as const }, include: { _count: { select: { usages: true } } } };
+
+/** A campus-scoped supervisor may only create or move events to one of their campuses. */
+export function assertCampusAllowed(scope: CampusScope, campusId: string | null): void {
+  if (scope && !campusScope.canManage(scope, campusId)) {
+    fail(403, campusId == null
+      ? 'Choose one of your campuses — events for all campuses are set up by admins and supervisors for every campus.'
+      : 'You can only put events at your own campuses.');
+  }
+}
+
+/**
+ * Adds the multi-day schedule to an event for API responses: sessions (cancelled ones flagged),
+ * when registration closes, the next session, and late-joiner pricing. `bookings` (Map
+ * sessionId → people booked) adds `booked` and `placesLeft` per session.
+ */
+export function withSchedule<E extends { sessions?: any[]; scheduleType?: string }>(ev: E, bookings: Map<string, number> | null = null) {
+  const sessions = (ev.sessions || []).map(({ _count, ...s }: any) => ({
+    ...s,
+    cancelled: !!s.cancelledAt,
+    hasCheckIns: (_count?.usages || 0) > 0,
+    ...(bookings ? { booked: bookings.get(s.id) || 0, placesLeft: s.capacity > 0 ? Math.max(0, s.capacity - (bookings.get(s.id) || 0)) : null } : {}),
+  }));
+  const active = sessionsUtil.activeSessions(sessions);
+  const now = new Date();
+  return {
+    ...ev,
+    sessions,
+    registrationClosesAt: sessionsUtil.registrationClosesAt(ev, sessions),
+    wholeCourseClosesAt: ev.scheduleType === 'sessions' ? sessionsUtil.wholeCourseClosesAt(ev, sessions) : null,
+    nextSession: ev.scheduleType === 'sessions' ? active.find((s: any) => new Date(s.endsAt) > now) || null : null,
+    lateJoin: ev.scheduleType === 'sessions' ? sessionsUtil.lateInfo(ev, sessions, now) : null,
+  };
+}
+
+/** The schedule/attendance fields from a create/update body. `current` is the saved event on update. */
+export function scheduleData(body: EventInput, current: Record<string, any> = {}): Record<string, any> {
+  const has = (k: string) => body[k] !== undefined;
+  const data: Record<string, any> = {};
+  if (has('scheduleType')) data.scheduleType = body.scheduleType === 'sessions' ? 'sessions' : 'single';
+  if (has('attendanceMode')) data.attendanceMode = body.attendanceMode === 'pick' ? 'pick' : 'whole';
+  if ((data.attendanceMode ?? current.attendanceMode) === 'pick' && (body.requiresParentalConsent ?? current.requiresParentalConsent) === true) {
+    throw sessionsUtil.sessionError("Choosing sessions isn't available on youth events (parental consent).");
+  }
+  if (has('checkInWindow')) data.checkInWindow = body.checkInWindow === 'session_only' ? 'session_only' : 'whole_day';
+  if (has('lateJoinEnabled')) data.lateJoinEnabled = body.lateJoinEnabled === true;
+  if (has('latePricing')) data.latePricing = ['prorata', 'fixed'].includes(body.latePricing) ? body.latePricing : 'full';
+  if (has('lateFixedPrice')) {
+    const n = parseFloat(body.lateFixedPrice);
+    data.lateFixedPrice = body.lateFixedPrice === null || body.lateFixedPrice === '' || isNaN(n) ? null : Math.max(0, n);
+  }
+  if (has('sessionReminders')) data.sessionReminders = sessionsUtil.normalizeReminders(body.sessionReminders) ?? null;
+  if (has('certificatesEnabled')) data.certificatesEnabled = body.certificatesEnabled === true;
+  if (has('certificateConfig')) data.certificateConfig = sessionsUtil.normalizeCertificateConfig(body.certificateConfig);
+  const latePricing = data.latePricing ?? current.latePricing;
+  const lateFixedPrice = data.lateFixedPrice !== undefined ? data.lateFixedPrice : current.lateFixedPrice;
+  if (latePricing === 'fixed' && (lateFixedPrice === null || lateFixedPrice === undefined) && (data.lateJoinEnabled ?? current.lateJoinEnabled)) {
+    throw sessionsUtil.sessionError('Enter the fixed late price, or choose another late price option');
+  }
+  return data;
+}
+
+/**
+ * Saves the session list and the "late joining until" session, inside the caller's transaction
+ * so a refused change saves nothing. Returns the change counts, or null when nothing was sent.
+ */
+export async function saveSchedule(tx: Prisma.TransactionClient, eventId: string, body: EventInput): Promise<Record<string, number> | null> {
+  sessionsUtil.forgetSchedule(eventId);
+  if (body.scheduleType === 'single') {
+    const used = await tx.ticketUsage.count({ where: { session: { eventId } } });
+    if (used > 0) throw sessionsUtil.sessionError("This event already has session check-ins, so it can't go back to a single date.");
+    await tx.eventSession.deleteMany({ where: { eventId } });
+    await tx.event.update({ where: { id: eventId }, data: { lateJoinUntilSessionId: null } });
+    return null;
+  }
+  if (!Array.isArray(body.sessions)) return null;
+  const { sessions, changes } = await sessionsUtil.syncEventSessions(tx, eventId, body.sessions);
+  if (body.lateJoinUntilSessionIndex !== undefined) {
+    const idx = parseInt(body.lateJoinUntilSessionIndex, 10);
+    const ordered = [...sessions].sort((a, b) => a.order - b.order);
+    const until = Number.isInteger(idx) && ordered[idx] && !ordered[idx].cancelledAt ? ordered[idx].id : null;
+    await tx.event.update({ where: { id: eventId }, data: { lateJoinUntilSessionId: until } });
+  }
+  return changes;
+}
+
+const yes = (v: unknown) => v === true || v === 'true';
+const notNo = (v: unknown) => !(v === false || v === 'false');
+
+/** Replaces the event's attendee form with the one sent (`{ isRequired, fields[] }`). */
+async function saveForm(eventId: string, formInput: any): Promise<void> {
+  if (!formInput) return;
+  try {
+    let form = await prisma.eventForm.findUnique({ where: { eventId } });
+    if (!form) form = await prisma.eventForm.create({ data: { id: uuidv4(), eventId, isRequired: !!formInput.isRequired } });
+    else await prisma.eventForm.update({ where: { id: form.id }, data: { isRequired: !!formInput.isRequired } });
+    await prisma.eventFormField.deleteMany({ where: { formId: form.id } });
+    const fields = Array.isArray(formInput.fields) ? formInput.fields : [];
+    for (let i = 0; i < fields.length; i++) {
+      const f = fields[i];
+      if (!f || !f.type || !f.label) continue;
+      await prisma.eventFormField.create({
+        data: {
+          id: uuidv4(), formId: form.id, type: f.type, label: String(f.label), isRequired: !!f.isRequired,
+          order: typeof f.order === 'number' ? f.order : i, helpText: f.helpText || null, options: f.options || undefined,
+        },
+      });
+    }
+  } catch (e: any) {
+    console.error('[events] Failed to save form/fields:', e?.message || e);
+    fail(400, 'Failed to save event form/fields');
+  }
+}
+
+/** Turns a helper's plain Error (session rules, series, campus) into a 400, like v1 did. */
+async function asClientErrors<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (e: any) {
+    if (e instanceof ServiceError || /^P\d{4}$/.test(String(e?.code || ''))) throw e;
+    throw new ServiceError(e?.statusCode || 400, e?.message || 'The event could not be saved');
+  }
+}
+
+/**
+ * A new event, with a "Main Ticket" at the event price (unless it's contact-only), its sessions
+ * and its attendee form. A campus-scoped supervisor must put it at one of their campuses.
+ */
+export function createEvent(body: EventInput, actor: Actor, ctx: Ctx) {
+  return asClientErrors(async () => {
+    const campusPick = await campuses.campusForEvent(body.campusId, { enabled: await campuses.campusesEnabled() });
+    if (campusPick.error) fail(400, campusPick.error);
+    // Not choosing a campus means all campuses, which a scoped supervisor can't create.
+    assertCampusAllowed(ctx.scope, campusPick.campusId === undefined ? null : campusPick.campusId);
+    const seriesId = await seriesUtil.seriesForEvent(body.seriesId);
+
+    const data: Record<string, any> = {
+      id: uuidv4(),
+      title: body.title,
+      description: body.description,
+      startDate: new Date(body.startDate),
+      endDate: new Date(body.endDate),
+      registrationDeadline: body.registrationDeadline ? new Date(body.registrationDeadline) : null,
+      goLiveAt: body.goLiveAt ? new Date(body.goLiveAt) : undefined,
+      price: parseFloat(body.price),
+      picture: body.picture,
+      updatedAt: new Date(),
+      createdById: actor.id,
+      redirectUrl: body.redirectUrl,
+      isHidden: yes(body.isHidden),
+      requiresAuth: notNo(body.requiresAuth),
+      requiresRegistration: notNo(body.requiresRegistration),
+      // A youth event needs names (with dates of birth), so it always takes them.
+      allowNamedAttendees: yes(body.allowNamedAttendees) || body.requiresParentalConsent === true,
+      requiresParentalConsent: body.requiresParentalConsent === true,
+      consentText: body.consentText ? String(body.consentText) : null,
+      consentCollectMedical: body.consentCollectMedical === true,
+      consentCollectEmergency: body.consentCollectEmergency === true,
+      consentCollectPhoto: body.consentCollectPhoto === true,
+      waitlistEnabled: body.waitlistEnabled === true,
+      allowTicketTransfer: body.allowTicketTransfer !== false,
+      collectGender: body.collectGender === true,
+      allowSponsorships: body.allowSponsorships === true,
+      sponsorshipGoalSpots: body.sponsorshipGoalSpots ? Math.max(1, parseInt(body.sponsorshipGoalSpots, 10) || 0) || null : null,
+      showSponsorshipProgress: body.showSponsorshipProgress !== false,
+      waitlistOfferHours: Math.min(168, Math.max(1, parseInt(body.waitlistOfferHours, 10) || 24)),
+      waitlistPartialOffers: body.waitlistPartialOffers !== false,
+      contactName: body.contactName || null,
+      contactPhone: body.contactPhone || null,
+      contactEmail: body.contactEmail || null,
+      location: body.location || null,
+      ...(campusPick.campusId !== undefined ? { campusId: campusPick.campusId } : {}),
+      ...(seriesId ? { seriesId } : {}),
+      ...scheduleData(body),
+    };
+    if (data.scheduleType === 'sessions') {
+      // Check the sessions before anything is saved; the dates come from them.
+      const bounds = sessionsUtil.scheduleBounds(sessionsUtil.normalizeSessionsInput(body.sessions).filter(s => !s.cancelled));
+      data.startDate = bounds.startDate;
+      data.endDate = bounds.endDate;
+    }
+
+    const event = await prisma.event.create({ data: data as Prisma.EventUncheckedCreateInput });
+    logAdminAction({
+      actorId: actor.id, actorRole: actor.role, action: 'event_created', targetType: 'Event', targetId: event.id,
+      metadata: { title: event.title, ...(body.clonedFromId ? { clonedFromId: String(body.clonedFromId) } : {}) }, ip: ctx.ip,
+    });
+    if (data.scheduleType === 'sessions') await prisma.$transaction(tx => saveSchedule(tx, event.id, body));
+
+    // A main ticket at the event price — contact-only events have nothing to book.
+    if (data.requiresRegistration !== false) {
+      await prisma.eventOption.create({ data: { id: uuidv4(), eventId: event.id, name: 'Main Ticket', price: event.price || 0, isMainTicket: true } })
+        .catch((e: any) => console.warn('[events] Failed to auto-create main ticket option:', e?.message || e));
+    }
+    await saveForm(event.id, body.form);
+
+    return withSchedule(await prisma.event.findUniqueOrThrow({ where: { id: event.id }, include: { sessions: SESSIONS_INCLUDE, eventOptions: true } }));
+  });
+}
+
+/**
+ * Edits an event: only the fields sent change. Its sessions save in the same transaction (a
+ * refused schedule change saves nothing); a changed consent text starts a new version; moving it
+ * to another series lets that series' followers hear about it. Closed (cashed-up) events can't
+ * change.
+ */
+export function updateEvent(eventId: string, body: EventInput, actor: Actor, ctx: Ctx) {
+  return asClientErrors(async () => {
+    const event = await prisma.event.findUnique({ where: { id: eventId } });
+    if (!event) return fail(404, 'Event not found');
+    // A closed (cashed-up) event's pricing/structure must not change under the reconciled totals.
+    await assertEventOpen(eventId);
+
+    const campusPick = await campuses.campusForEvent(body.campusId, { enabled: await campuses.campusesEnabled(), currentCampusId: event.campusId });
+    if (campusPick.error) fail(400, campusPick.error);
+    const campusChanged = campusPick.campusId !== undefined && campusPick.campusId !== event.campusId;
+    const seriesPick = await seriesUtil.seriesForEvent(body.seriesId);
+    // Moved into another series: that series' followers hear about it (once it's live).
+    const seriesChanged = seriesPick !== undefined && seriesPick !== event.seriesId;
+    if (campusChanged) assertCampusAllowed(ctx.scope, campusPick.campusId ?? null);
+
+    const keep = <K extends keyof typeof event>(k: K, v: unknown, map: (x: any) => unknown = x => x) => (v !== undefined ? map(v) : event[k]);
+    const requiresParentalConsent = body.requiresParentalConsent ?? event.requiresParentalConsent;
+    const data: Record<string, any> = {
+      title: body.title || event.title,
+      description: keep('description', body.description),
+      startDate: body.startDate ? new Date(body.startDate) : event.startDate,
+      endDate: body.endDate ? new Date(body.endDate) : event.endDate,
+      registrationDeadline: keep('registrationDeadline', body.registrationDeadline, v => (v ? new Date(v) : null)),
+      goLiveAt: body.goLiveAt !== undefined ? (body.goLiveAt ? new Date(body.goLiveAt) : new Date()) : (event.goLiveAt || undefined),
+      price: body.price ? parseFloat(body.price) : event.price,
+      picture: keep('picture', body.picture),
+      isActive: keep('isActive', body.isActive),
+      isHidden: body.isHidden !== undefined ? yes(body.isHidden) : (event.isHidden ?? false),
+      requiresAuth: body.requiresAuth !== undefined ? notNo(body.requiresAuth) : (event.requiresAuth ?? true),
+      requiresRegistration: body.requiresRegistration !== undefined ? notNo(body.requiresRegistration) : (event.requiresRegistration ?? true),
+      allowNamedAttendees: requiresParentalConsent === true ? true : (body.allowNamedAttendees !== undefined ? yes(body.allowNamedAttendees) : event.allowNamedAttendees),
+      requiresParentalConsent: keep('requiresParentalConsent', body.requiresParentalConsent, v => v === true),
+      consentCollectMedical: keep('consentCollectMedical', body.consentCollectMedical, v => v === true),
+      consentCollectEmergency: keep('consentCollectEmergency', body.consentCollectEmergency, v => v === true),
+      consentCollectPhoto: keep('consentCollectPhoto', body.consentCollectPhoto, v => v === true),
+      waitlistEnabled: keep('waitlistEnabled', body.waitlistEnabled, v => v === true),
+      allowTicketTransfer: keep('allowTicketTransfer', body.allowTicketTransfer, v => v !== false),
+      collectGender: keep('collectGender', body.collectGender, v => v === true),
+      allowSponsorships: keep('allowSponsorships', body.allowSponsorships, v => v === true),
+      sponsorshipGoalSpots: keep('sponsorshipGoalSpots', body.sponsorshipGoalSpots, v => (v ? Math.max(1, parseInt(v, 10) || 0) || null : null)),
+      showSponsorshipProgress: keep('showSponsorshipProgress', body.showSponsorshipProgress, v => v !== false),
+      waitlistOfferHours: keep('waitlistOfferHours', body.waitlistOfferHours, v => Math.min(168, Math.max(1, parseInt(v, 10) || 24))),
+      waitlistPartialOffers: keep('waitlistPartialOffers', body.waitlistPartialOffers, v => v !== false),
+      // Editing the consent text starts a new version; parents who already agreed keep their
+      // record of the old one (supervisors can re-request consent).
+      ...(body.consentText !== undefined && String(body.consentText || '') !== String(event.consentText || '')
+        ? { consentText: body.consentText ? String(body.consentText) : null, consentTextVersion: (event.consentTextVersion || 1) + 1 }
+        : {}),
+      contactName: keep('contactName', body.contactName, v => v || null),
+      contactPhone: keep('contactPhone', body.contactPhone, v => v || null),
+      contactEmail: keep('contactEmail', body.contactEmail, v => v || null),
+      location: keep('location', body.location, v => v || null),
+      ...(campusChanged ? { campusId: campusPick.campusId } : {}),
+      ...(seriesChanged ? { seriesId: seriesPick, seriesAnnouncedAt: null } : {}),
+      updatedAt: new Date(),
+      redirectUrl: keep('redirectUrl', body.redirectUrl),
+      ...scheduleData(body, event),
+    };
+    // A multi-session event's dates come from its sessions (set by saveSchedule).
+    if ((data.scheduleType ?? event.scheduleType) === 'sessions') {
+      data.startDate = event.startDate;
+      data.endDate = event.endDate;
+      if (Array.isArray(body.sessions)) sessionsUtil.normalizeSessionsInput(body.sessions);
+      else if (event.scheduleType !== 'sessions') throw sessionsUtil.sessionError('Add the sessions for a multi-session event');
+    }
+
+    // Event fields and sessions save together: a refused schedule change saves nothing.
+    const scheduleBody = data.scheduleType === 'single' && event.scheduleType === 'sessions' ? { scheduleType: 'single' } : body;
+    let sessionChanges: Record<string, number> | null = null;
+    const saved = await prisma.$transaction(async (tx) => {
+      const updated = await tx.event.update({ where: { id: eventId }, data });
+      sessionChanges = updated.scheduleType === 'sessions' || scheduleBody.scheduleType === 'single' ? await saveSchedule(tx, updated.id, scheduleBody) : null;
+      return updated;
+    });
+    sessionsUtil.forgetSchedule(saved.id);
+    if (campusChanged) {
+      logAdminAction({ actorId: actor.id, actorRole: actor.role, action: 'event_campus_changed', targetType: 'Event', targetId: saved.id, metadata: { from: event.campusId, to: campusPick.campusId }, ip: ctx.ip });
+    }
+    const changes = sessionChanges as Record<string, number> | null;
+    if (changes && Object.values(changes).some(n => n > 0)) {
+      logAdminAction({ actorId: actor.id, actorRole: actor.role, action: 'event_sessions_changed', targetType: 'Event', targetId: saved.id, metadata: changes, ip: ctx.ip });
+    }
+    await saveForm(saved.id, body.form);
+    logAdminAction({ actorId: actor.id, actorRole: actor.role, action: 'event_updated', targetType: 'Event', targetId: eventId, metadata: { changedKeys: Object.keys(body || {}) }, ip: ctx.ip });
+
+    const fresh = withSchedule(await prisma.event.findUniqueOrThrow({ where: { id: saved.id }, include: { sessions: SESSIONS_INCLUDE } }));
+    return { ...fresh, sessionChanges: changes };
+  });
+}
+
+/** "Deleting" an event deactivates it (registrations, payments and tickets stay). Admins only. */
+export async function deactivateEvent(eventId: string, actor: Actor, ctx: Ctx) {
+  const event = await prisma.event.findUnique({ where: { id: eventId }, select: { id: true } });
+  if (!event) return fail(404, 'Event not found');
+  const updated = await prisma.event.update({ where: { id: eventId }, data: { isActive: false, updatedAt: new Date() } });
+  logAdminAction({ actorId: actor.id, actorRole: actor.role, action: 'event_deleted', targetType: 'Event', targetId: eventId, ip: ctx.ip });
+  return updated;
+}
+
+export type ManagedListOptions = { includePast?: boolean; includeInactive?: boolean; excludeClosed?: boolean; campus?: string };
+
+/**
+ * Every event staff may see (hidden ones too) — upcoming by default; past, inactive and
+ * closed (cashed-up) on request; limited to their campuses when they're campus-scoped. With
+ * ticket options (tiers, variants), the attendee form, sessions, campus and series.
+ */
+export async function listManagedEvents(opts: ManagedListOptions, ctx: Ctx) {
+  const where: Record<string, any> = {};
+  if (!opts.includeInactive) where.isActive = true;
+  if (!opts.includePast) where.endDate = { gte: new Date() };
+  if (opts.excludeClosed) where.cashupStatus = { not: 'closed' };
+  // ?campus=<id, slug or 'all'>: one campus's events, or only church-wide ones.
+  const enabled = await campuses.campusesEnabled();
+  Object.assign(where, campuses.campusWhere(enabled ? await campuses.resolveCampusFilter(opts.campus) : '', { enabled }));
+  const scoped = campusScope.withScope(where, campusScope.eventWhere(ctx.scope));
+  const events = await prisma.event.findMany({
+    where: scoped,
+    include: {
+      eventOptions: { include: { earlyBirdTiers: true, variants: { orderBy: { order: 'asc' } } } },
+      form: { include: { fields: true } },
+      sessions: SESSIONS_INCLUDE,
+      campus: { select: campuses.EVENT_CAMPUS_SELECT },
+      series: SERIES_SELECT,
+    },
+    orderBy: { startDate: 'asc' },
+  });
+  return events.map(ev => withSchedule(ev));
+}
+
+const RECIPIENT_SELECT = { id: true, name: true, email: true, role: true } as const;
+
+/** Who gets this event's registration, payment and daily-summary emails. */
+export async function getNotifyRecipients(eventId: string) {
+  const event = await prisma.event.findUnique({ where: { id: eventId }, select: { notifyRecipients: { select: RECIPIENT_SELECT } } });
+  if (!event) return fail(404, 'Event not found');
+  return event.notifyRecipients;
+}
+
+export async function setNotifyRecipients(eventId: string, userIds: string[]) {
+  if (!Array.isArray(userIds)) fail(400, 'userIds must be an array');
+  const event = await prisma.event.findUnique({ where: { id: eventId }, select: { id: true } });
+  if (!event) return fail(404, 'Event not found');
+  const updated = await prisma.event.update({
+    where: { id: eventId },
+    data: { notifyRecipients: { set: userIds.map(id => ({ id })) } },
+    include: { notifyRecipients: { select: RECIPIENT_SELECT } },
+  });
+  return updated.notifyRecipients;
+}
+
+/** Copies allocation groups (and, for admins, planned costs) from another event into this one. */
+export async function copySetupFrom(eventId: string, fromEventId: string, actor: Actor) {
+  if (!fromEventId) fail(400, 'fromEventId is required');
+  const { copyEventSetup } = require('../utils/eventClone') as { copyEventSetup(from: string, to: string, opts: { withCosts: boolean }): Promise<unknown> };
+  return copyEventSetup(String(fromEventId), eventId, { withCosts: actor.role === 'admin' });
+}

backend/src/services/payments.ts

@@ -0,0 +1,88 @@
+/**
+ * Paying a registration online (1.51.1). Moved from paymentController.createCheckout so
+ * POST /api/payments/checkout (v1) and POST /api/v2/registrations/:id/checkout share it.
+ */
+import { prisma } from '../v2/legacy';
+import { fail, ServiceError } from './errors';
+import type { Role } from './registrations';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- the JS helpers below aren't typed yet */
+const payments = require('../payments') as { MIN_ONLINE_AMOUNT: number };
+const { createRegistrationCheckout } = require('../payments/checkouts') as {
+  createRegistrationCheckout(registrationId: string, userId: string, opts: { successUrl?: string; cancelUrl?: string; failureUrl?: string; donationAmount?: number; amount?: number | null; provider?: string | null }): Promise<{
+    checkoutId: string; redirectUrl: string; provider: string; amount: number; registration: { id: string; eventId: string; eventTitle: string };
+  }>;
+};
+const pricing = require('../utils/pricing') as {
+  refreshPricingForRegistration(id: string): Promise<{ changed: boolean }>;
+  computeRegistrationTotalDue(registration: any, at: Date): number;
+};
+const { assertEventOpen } = require('../utils/cashupUtils') as { assertEventOpen(eventId: string): Promise<unknown> };
+
+export type CheckoutOptions = {
+  /** Pay only this much of the balance (staff taking part payments). */
+  amount?: number | null;
+  /** An optional donation added on top (the register form's "Donation amount"). */
+  donationAmount?: number | null;
+  provider?: string | null;
+  successUrl?: string;
+  cancelUrl?: string;
+  failureUrl?: string;
+};
+
+export type CheckoutResult =
+  | { priceUpdated: true; newTotal: number; message: string }
+  | { priceUpdated?: false; checkoutId: string; redirectUrl: string; provider: string; amount: number; registration: { id: string; eventId: string; eventTitle: string } };
+
+/**
+ * Starts an online payment for what's owed on a registration (the owner, or a supervisor or
+ * admin). If an early-bird price ran out since it was made, nothing is charged: the caller is
+ * told the new total to show first.
+ */
+export async function startRegistrationCheckout(registrationId: string, actor: { id: string; role: Role }, opts: CheckoutOptions = {}): Promise<CheckoutResult> {
+  const reg = await prisma.registration.findUnique({ where: { id: registrationId }, select: { userId: true, eventId: true, event: { select: { endDate: true } } } });
+  if (!reg) return fail(404, 'Registration not found');
+  const staffSide = actor.role === 'admin' || actor.role === 'supervisor';
+  if (reg.userId !== actor.id && !staffSide) fail(403, 'Not authorized to create checkout for this registration');
+  // If event is in the past, block self-service payment (mirrors the registration-edit block)
+  if (!staffSide && reg.event?.endDate && new Date(reg.event.endDate).getTime() < Date.now()) {
+    fail(400, 'This event has already ended; payment can no longer be made for this registration');
+  }
+  try {
+    await assertEventOpen(reg.eventId);
+  } catch (e: any) {
+    throw new ServiceError(e.message === 'Event not found' ? 404 : 400, e.message);
+  }
+
+  // Refresh early-bird pricing — updates priceSnapshot if any tier has expired or sold out.
+  // Must run before the balance is worked out so the checkout charges the right price.
+  const { changed } = await pricing.refreshPricingForRegistration(registrationId);
+  if (changed) {
+    const fresh = await prisma.registration.findUniqueOrThrow({
+      where: { id: registrationId },
+      include: { registrationOptions: { include: { eventOption: { include: { earlyBirdTiers: true } }, tranches: true } }, payments: true },
+    });
+    const newTotal = pricing.computeRegistrationTotalDue(fresh, new Date());
+    const totalPaid = fresh.payments.reduce((s, p) => s + p.amount, 0);
+    return {
+      priceUpdated: true,
+      newTotal: Math.max(0, newTotal - totalPaid),
+      message: 'One or more early-bird prices have changed since your registration was created. Please review the updated total before proceeding.',
+    };
+  }
+
+  const urls = { successUrl: opts.successUrl, cancelUrl: opts.cancelUrl, failureUrl: opts.failureUrl, provider: opts.provider ?? null };
+
+  // Part of the balance (supervisor payments page)
+  if (opts.amount !== undefined && opts.amount !== null && !isNaN(Number(opts.amount))) {
+    return createRegistrationCheckout(registrationId, actor.id, { ...urls, amount: Number(opts.amount) });
+  }
+
+  let donation = 0;
+  if (opts.donationAmount !== undefined && opts.donationAmount !== null) {
+    donation = Math.round(Number(opts.donationAmount) * 100) / 100;
+    if (!(donation >= 0) || donation > 100000) fail(400, 'Invalid donation amount');
+    if (donation > 0 && donation < payments.MIN_ONLINE_AMOUNT) fail(400, `Minimum donation is R${payments.MIN_ONLINE_AMOUNT}`);
+  }
+  return createRegistrationCheckout(registrationId, actor.id, { ...urls, donationAmount: donation });
+}

backend/src/services/registrations.ts

@@ -0,0 +1,497 @@
+/**
+ * Making and cancelling registrations (1.51.1). Moved here from registrationController.js so
+ * POST /api/registrations (v1) and POST /api/v2/registrations run the same code. Errors are
+ * ServiceErrors carrying their HTTP status.
+ */
+import { v4 as uuidv4 } from 'uuid';
+import { prisma } from '../v2/legacy';
+import { fail, ServiceError } from './errors';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- the JS helpers below aren't typed yet */
+const { generateTicketsForRegistration } = require('../utils/ticketUtils') as { generateTicketsForRegistration(id: string): Promise<unknown> };
+const pricing = require('../utils/pricing') as {
+  resolveOptionPrice(option: any, qty: number, buyer: any): Promise<{ price: number; tierId: string | null }>;
+  resolveVariantTierPrice(option: any, variantId: string, qty: number, buyer: any): Promise<{ price: number; tierId: string | null }>;
+  computeRegistrationTotalDue(registration: any, at: Date): number;
+  attachComputedTotals<T>(registration: T): T & { totalDueComputed: number };
+};
+const coupons = require('../utils/coupons') as {
+  buildCouponLines(registration: any): any[];
+  previewCoupon(args: { code: string; eventId: string; user: any; lines: any[] }): Promise<unknown>;
+  applyCouponToRegistration(args: { registrationId: string; code: string }): Promise<unknown>;
+  recalculateRegistrationDiscount(registrationId: string): Promise<number>;
+  releaseRegistrationCoupons(registrationId: string): Promise<unknown>;
+};
+const attendeesUtil = require('../utils/attendees') as {
+  lineKey(eventOptionId: string, variantId?: string | null): string;
+  validateAttendees(event: any, places: Record<string, number>, attendees: unknown, existing: Record<string, number>): any[];
+  createAttendees(registrationId: string, attendees: any[]): Promise<unknown>;
+  namedPlacesByKey(registrationId: string): Promise<Record<string, number>>;
+};
+const { findAccountByContact } = require('../utils/accountMatch') as { findAccountByContact(c: { email?: string; phone?: string }): Promise<{ user: { id: string } | null; conflict?: boolean }> };
+const { ensureConsentRequests } = require('../utils/consent') as { ensureConsentRequests(registrationId: string): Promise<unknown> };
+const { takenCount } = require('../utils/stock') as { takenCount(where: object, opts?: { excludeEntryId?: string | null }): Promise<number> };
+const waitlist = require('../utils/waitlist') as { findOfferByToken(token: string): Promise<any>; queueWaitlist(eventId: string): void };
+const { reservedOptionIds } = require('../utils/volunteers') as { reservedOptionIds(event: any): string[] };
+const { BUNDLE_APPS_INCLUDE } = require('../utils/bundles') as { BUNDLE_APPS_INCLUDE: any };
+const sessions = require('../utils/sessions') as {
+  registrationClosesAt(event: any, sessions: any[]): Date;
+  wholeCourseClosesAt(event: any, sessions: any[]): Date;
+  expandPickLines(event: any, options: any[], opts: { now: Date }): any[];
+  assertSessionCapacity(event: any, lines: any[], registrationId?: string, opts?: { excludeEntryId?: string }): Promise<void>;
+  mergeSessionIds(a: string[] | null | undefined, b: string[] | null | undefined): string[];
+};
+const { assertEventOpen } = require('../utils/cashupUtils') as { assertEventOpen(eventId: string, res?: unknown): Promise<unknown> };
+const { logAdminAction } = require('../utils/adminAudit') as { logAdminAction(entry: object): Promise<void> };
+
+export type Role = 'admin' | 'supervisor' | 'staff' | 'user';
+export type Actor = { id: string; role: Role; email?: string } | null;
+
+export const TICKET_DELIVERY = ['payer', 'each'] as const;
+export const isStaffRole = (role: string | undefined | null): boolean => ['admin', 'supervisor', 'staff'].includes(String(role));
+
+// Named attendees for API responses, with whether their ticket has been issued/used.
+export const ATTENDEES_INCLUDE = {
+  orderBy: { order: 'asc' as const },
+  include: {
+    ticket: { select: { id: true, isUsed: true } },
+    // Latest consent request (youth events) — it decides check-in.
+    consentRequests: { orderBy: { createdAt: 'desc' as const }, take: 1, select: { id: true, status: true, respondedAt: true, lastSentAt: true, textVersion: true } },
+  },
+};
+
+// Active coupon on a registration, for API responses (the discount itself is
+// Registration.discountTotal).
+export const ACTIVE_COUPONS_INCLUDE = {
+  where: { releasedAt: null },
+  select: { id: true, discountAmount: true, createdAt: true, coupon: { select: { id: true, code: true, type: true, value: true, description: true } } },
+};
+
+// 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.
+export function queueConsentRequests(registrationId: string): void {
+  ensureConsentRequests(registrationId).catch((e: any) => console.error('[consent] Failed to send requests:', e?.message || e));
+}
+
+type Line = { eventOptionId: string; variantId?: string | null; sessionId?: string | null; quantity: number | string };
+
+/**
+ * Places each line will have once `requested` is added to `existingLines` — used to
+ * check attendee names against what's actually being bought.
+ */
+export function placesAfter(existingLines: Line[] | undefined, requested: Line[] | undefined): Record<string, number> {
+  const out: Record<string, number> = {};
+  // Picked-session lines take no attendee names.
+  for (const l of [...(existingLines || []), ...(requested || [])].filter(x => !x.sessionId)) {
+    const k = attendeesUtil.lineKey(l.eventOptionId, l.variantId);
+    out[k] = (out[k] || 0) + Number(l.quantity || 0);
+  }
+  return out;
+}
+
+/**
+ * Coupon lines for options that haven't been saved yet, so a code can be checked
+ * before anything is created. Mirrors buildCouponLines for one tranche per option.
+ */
+export function pendingCouponLines(event: { eventOptions: { id: string }[] }, resolvedOptions: any[]): any[] {
+  return coupons.buildCouponLines({
+    registrationOptions: resolvedOptions.map(o => ({
+      eventOptionId: o.eventOptionId,
+      variantId: o.variantId || null,
+      quantity: o.quantity,
+      eventOption: event.eventOptions.find(eo => eo.id === o.eventOptionId),
+      tranches: [{ quantity: o.quantity, priceSnapshot: o.priceSnapshot, appliedTierId: o.appliedTierId }],
+    })),
+  });
+}
+
+/**
+ * Price one requested option for this buyer: early-bird tiers, then variant/option price,
+ * then the staff price for Staff and above. Returns { priceSnapshot, appliedTierId }.
+ */
+export async function priceRequestedOption(eventOption: any, variantId: string | null, qty: number, buyer: any): Promise<{ priceSnapshot: number; appliedTierId: string | null }> {
+  try {
+    const resolved = variantId
+      ? await pricing.resolveVariantTierPrice(eventOption, variantId, qty, buyer)
+      : await pricing.resolveOptionPrice(eventOption, qty, buyer);
+    return { priceSnapshot: resolved.price, appliedTierId: resolved.tierId };
+  } catch {
+    const variant = variantId ? (eventOption.variants || []).find((v: any) => v.id === variantId) : null;
+    const price = variant && variant.price !== null && variant.price !== undefined ? variant.price : eventOption.price;
+    return { priceSnapshot: Number(price || 0), appliedTierId: null };
+  }
+}
+
+/**
+ * Check overall stock availability for an EventOption. Places held for live waitlist
+ * offers count as taken, except the offer being claimed (`excludeEntryId`).
+ */
+export async function checkOptionStock(option: { id: string; stockLimit: number }, requestedQty: number, excludeEntryId: string | null = null, sessionId: string | null = null) {
+  if (!option.stockLimit || option.stockLimit === 0) return { available: true, remaining: null as number | null };
+  const remaining = option.stockLimit - await takenCount({ eventOptionId: option.id, sessionId }, { excludeEntryId });
+  return { available: remaining >= requestedQty, remaining };
+}
+
+/** Check stock availability for a specific variant (same rules as checkOptionStock). */
+export async function checkVariantStock(variant: { id: string; eventOptionId: string; stockLimit: number | null }, requestedQty: number, excludeEntryId: string | null = null, sessionId: string | null = null) {
+  if (!variant.stockLimit || variant.stockLimit === 0) return { available: true, remaining: null as number | null };
+  const remaining = variant.stockLimit - await takenCount({ eventOptionId: variant.eventOptionId, variantId: variant.id, sessionId }, { excludeEntryId });
+  return { available: remaining >= requestedQty, remaining };
+}
+
+export type RequestedOption = { eventOptionId: string; quantity: number; variantId?: string | null; sessionIds?: string[] };
+export type CreateRegistrationInput = {
+  eventId: string;
+  options: RequestedOption[];
+  guestName?: string;
+  guestEmail?: string;
+  guestPhone?: string;
+  couponCode?: string;
+  attendees?: unknown[];
+  ticketDelivery?: string;
+  waitlistToken?: string;
+  analyticsSessionId?: string;
+};
+
+const FULL_INCLUDE = {
+  registrationOptions: { include: { eventOption: true, tranches: true } },
+  event: true,
+  user: { select: { id: true, name: true, email: true, phoneNumber: true } },
+} as const;
+
+/**
+ * Registers someone for an event (online, a guest for a free event, or with a waitlist link):
+ * checks the event is open, prices each line (early-bird, variant, staff price), checks stock
+ * and session places, adds to an existing registration for the same person and event, applies
+ * bundle deals and a coupon, and issues tickets straight away when nothing is owed.
+ */
+export async function createRegistration(input: CreateRegistrationInput, actor: Actor) {
+  try {
+    return await create(input, actor);
+  } catch (e: any) {
+    // The helpers (coupons, attendee names, session places…) throw plain Errors written for
+    // people; like v1, those are the caller's problem (400) unless they carry a status.
+    if (e instanceof ServiceError || /^P\d{4}$/.test(String(e?.code || ''))) throw e;
+    throw new ServiceError(e?.statusCode || 400, e?.message || 'Registration failed');
+  }
+}
+
+async function create(input: CreateRegistrationInput, actor: Actor) {
+  const { eventId, options, guestName, guestEmail, guestPhone, couponCode, attendees, ticketDelivery, waitlistToken, analyticsSessionId } = input;
+
+  const event = await prisma.event.findUnique({
+    where: { id: eventId },
+    include: { eventOptions: { include: { earlyBirdTiers: true, variants: true } }, sessions: true },
+  });
+  if (!event) return fail(404, 'Event not found');
+  if (!event.isActive) return fail(400, 'Event is not active');
+  if (event.cashupStatus === 'closed') return fail(400, 'This event is closed and no longer accepting registrations.');
+
+  // A waitlist claim link: its token identifies the person and releases the places
+  // held for them. It works without logging in, the same way a consent link does.
+  let waitlistOffer: any = null;
+  if (waitlistToken) {
+    waitlistOffer = await waitlist.findOfferByToken(waitlistToken);
+    if (!waitlistOffer || waitlistOffer.eventId !== eventId) fail(400, 'This waitlist link is not valid.');
+    if (waitlistOffer.status !== 'offered') fail(400, `This waitlist offer has ${waitlistOffer.status === 'claimed' ? 'already been used' : 'expired'}.`);
+    if (new Date(waitlistOffer.offerExpiresAt) < new Date()) fail(400, 'This waitlist offer has expired.');
+    if (actor && actor.id !== waitlistOffer.userId) fail(403, 'This waitlist offer belongs to someone else.');
+  }
+
+  // Enforce auth unless event explicitly opts out
+  if (event.requiresAuth !== false && !actor && !waitlistOffer) fail(401, 'Authentication required for this event');
+
+  // Unauthenticated guest registration is only permitted for free events
+  if (!actor && !waitlistOffer) {
+    const requestedTotal = (options || []).reduce((sum, opt) => {
+      const eo = event.eventOptions.find(o => o.id === opt.eventOptionId);
+      return sum + ((eo?.price || 0) * (opt.quantity || 1));
+    }, 0);
+    if (requestedTotal > 0) fail(400, 'Guest registration is only available for free events. Please create an account to pay for tickets.');
+  }
+
+  // Resolve userId — authenticated or guest
+  let userId: string;
+  if (actor) {
+    userId = actor.id;
+  } else if (waitlistOffer) {
+    userId = waitlistOffer.userId;
+  } else {
+    // Guest registration: find existing user by email or create inactive placeholder
+    if (!guestEmail || !guestName) return fail(400, 'Name and email are required for unauthenticated registration');
+    const match = await findAccountByContact({ email: guestEmail, phone: guestPhone });
+    if (match.conflict) fail(409, 'This email and phone number belong to two different accounts. Please log in, or check your details.');
+    if (match.user) {
+      userId = match.user.id;
+    } else {
+      const newGuest = await prisma.user.create({
+        data: { id: uuidv4(), name: guestName, email: guestEmail, password: '', phoneNumber: guestPhone || null, isActive: false, updatedAt: new Date() },
+      });
+      userId = newGuest.id;
+    }
+  }
+
+  // Enforce registration cutoff for public registrations (multi-day events close when
+  // the first session starts, or later with late joining — see utils/sessions.js).
+  const now = new Date();
+  if (now >= sessions.registrationClosesAt(event, event.sessions)) fail(400, 'Registration is closed for this event');
+
+  if (!options || !Array.isArray(options) || options.length === 0) fail(400, 'At least one option must be selected');
+
+  // "Pick sessions" options become one line per chosen session; whole-course tickets
+  // on such an event still close when the whole course does.
+  const lines = sessions.expandPickLines(event, options, { now });
+  // (An all-sessions ticket with sessions ticked is checked per session instead.)
+  if (event.attendanceMode === 'pick' && lines.some(l => !l.sessionId && !l.sessionIds?.length) && now >= sessions.wholeCourseClosesAt(event, event.sessions)) {
+    fail(400, 'Whole-course tickets are no longer on sale — choose the sessions you want instead.');
+  }
+  await sessions.assertSessionCapacity(event, lines, undefined, { excludeEntryId: waitlistOffer?.id });
+
+  // Validate each option and resolve prices / check stock. Options are independent of each
+  // other, so resolve them concurrently. The kids check-in and volunteer tickets are handed
+  // out by staff, never sold.
+  const reserved = new Set(isStaffRole(actor?.role) ? [] : reservedOptionIds(event));
+  const buyerFor = async () => actor || (waitlistOffer ? await prisma.user.findUnique({ where: { id: waitlistOffer.userId }, select: { id: true, role: true } }) : null);
+  const resolvedOptions = await Promise.all(lines.map(async (option: any) => {
+    const eventOption = event.eventOptions.find(eo => eo.id === option.eventOptionId);
+    if (!eventOption || reserved.has(eventOption.id)) fail(400, `Option with ID ${option.eventOptionId} not found for this event`);
+    if (!option.quantity || option.quantity < 1) fail(400, 'Quantity must be at least 1');
+    const qty = option.quantity;
+
+    // (A failing count doesn't block the sale — only a real shortage does.)
+    const stockCheck = await checkOptionStock(eventOption!, qty, waitlistOffer?.id, option.sessionId).catch(() => ({ available: true, remaining: null }));
+    if (!stockCheck.available) fail(400, `"${eventOption!.name}" is sold out or does not have enough stock (${stockCheck.remaining ?? 0} remaining).`);
+
+    const variantId: string | null = option.variantId || null;
+    if (variantId) {
+      const variant = (eventOption!.variants || []).find(v => v.id === variantId);
+      if (!variant) return fail(400, `Variant not found for option "${eventOption!.name}"`);
+      const vStock = await checkVariantStock(variant, qty, waitlistOffer?.id, option.sessionId).catch(() => ({ available: true, remaining: null }));
+      if (!vStock.available) fail(400, `Variant "${variant.name}" is sold out (${vStock.remaining ?? 0} remaining).`);
+    }
+
+    // Variant-level tiers take priority, then option-level tiers, then base prices, then
+    // the staff price for Staff and above.
+    const { priceSnapshot, appliedTierId } = await priceRequestedOption(eventOption, variantId, qty, await buyerFor());
+    return { ...option, variantId, appliedTierId, priceSnapshot: priceSnapshot ?? eventOption!.price };
+  }));
+
+  // Check a coupon code before anything is saved, so a bad code doesn't leave a
+  // half-made registration behind. It's applied (and re-checked under a lock) below.
+  if (couponCode) {
+    const buyer = actor ? { id: actor.id, role: actor.role, email: actor.email } : null;
+    await coupons.previewCoupon({ code: couponCode, eventId, user: buyer, lines: pendingCouponLines(event, resolvedOptions) });
+  }
+
+  // Check for existing non-cancelled registration for this user+event → merge instead
+  const existingReg = await prisma.registration.findFirst({
+    where: { userId, eventId, status: { not: 'cancelled' } },
+    include: { registrationOptions: true },
+  });
+
+  // Attendee names are checked against the places the registration will have after
+  // this purchase, counting names already given on an existing registration.
+  const cleanAttendees = attendeesUtil.validateAttendees(
+    event,
+    placesAfter(existingReg?.registrationOptions, resolvedOptions),
+    attendees,
+    existingReg ? await attendeesUtil.namedPlacesByKey(existingReg.id) : {},
+  );
+  if (ticketDelivery !== undefined && !(TICKET_DELIVERY as readonly string[]).includes(ticketDelivery)) fail(400, "ticketDelivery must be 'payer' or 'each'");
+
+  let registrationId: string;
+  let isNewRegistration = false;
+  if (existingReg) {
+    // Merge: add a new price tranche per requested option into the existing registration.
+    // Never overwrite an existing row's priceSnapshot/quantity in place — that would blend
+    // tickets bought at different early-bird prices into a single (wrong) price. Each
+    // purchase gets its own tranche; the RegistrationOption row stays a maintained aggregate.
+    for (const opt of resolvedOptions) {
+      // Match on eventOptionId + variantId (+ session, for picked sessions) for correct row
+      const existing = existingReg.registrationOptions.find(
+        ro => ro.eventOptionId === opt.eventOptionId && (ro.variantId || null) === (opt.variantId || null) && (ro.sessionId || null) === (opt.sessionId || null),
+      );
+      if (existing) {
+        await prisma.$transaction([
+          prisma.registrationOptionTranche.create({
+            data: { id: uuidv4(), registrationOptionId: existing.id, quantity: opt.quantity, priceSnapshot: opt.priceSnapshot, appliedTierId: opt.appliedTierId || null },
+          }),
+          prisma.registrationOption.update({
+            where: { id: existing.id },
+            data: { quantity: existing.quantity + opt.quantity, priceSnapshot: opt.priceSnapshot, appliedTierId: opt.appliedTierId || null, ...(existing.sessionId ? {} : { sessionIds: sessions.mergeSessionIds(existing.sessionIds, opt.sessionIds) }) },
+          }),
+        ]);
+      } else {
+        await prisma.registrationOption.create({
+          data: {
+            id: uuidv4(),
+            registrationId: existingReg.id,
+            eventOptionId: opt.eventOptionId,
+            quantity: opt.quantity,
+            variantId: opt.variantId || null,
+            sessionId: opt.sessionId || null,
+            sessionIds: opt.sessionIds || [],
+            appliedTierId: opt.appliedTierId || null,
+            priceSnapshot: opt.priceSnapshot,
+            tranches: { create: [{ id: uuidv4(), quantity: opt.quantity, priceSnapshot: opt.priceSnapshot, appliedTierId: opt.appliedTierId || null }] },
+          },
+        });
+      }
+    }
+    // Only downgrade from paid if the newly added items actually cost something
+    const newItemsCost = resolvedOptions.reduce((sum, opt) => sum + ((opt.priceSnapshot || 0) * (opt.quantity || 0)), 0);
+    await prisma.registration.update({
+      where: { id: existingReg.id },
+      data: existingReg.status === 'paid' && newItemsCost > 0 ? { status: 'partial_paid', updatedAt: new Date() } : { updatedAt: new Date() },
+    });
+    registrationId = existingReg.id;
+  } else {
+    isNewRegistration = true;
+    registrationId = uuidv4();
+    await prisma.registration.create({
+      data: {
+        id: registrationId,
+        userId,
+        eventId,
+        updatedAt: new Date(),
+        registrationOptions: {
+          create: resolvedOptions.map(option => ({
+            id: uuidv4(),
+            eventOptionId: option.eventOptionId,
+            quantity: option.quantity,
+            variantId: option.variantId || null,
+            sessionId: option.sessionId || null,
+            sessionIds: option.sessionIds || [],
+            appliedTierId: option.appliedTierId || null,
+            priceSnapshot: option.priceSnapshot,
+            tranches: { create: [{ id: uuidv4(), quantity: option.quantity, priceSnapshot: option.priceSnapshot, appliedTierId: option.appliedTierId || null }] },
+          })),
+        },
+      },
+    });
+  }
+
+  if (cleanAttendees.length > 0) {
+    await attendeesUtil.createAttendees(registrationId, cleanAttendees);
+    queueConsentRequests(registrationId);
+  }
+  if (waitlistOffer) {
+    await prisma.waitlistEntry.update({
+      where: { id: waitlistOffer.id },
+      data: { status: 'claimed', claimedAt: new Date(), registrationId, offerTokenHash: null },
+    });
+  }
+  if (ticketDelivery) {
+    await prisma.registration.update({ where: { id: registrationId }, data: { ticketDelivery: ticketDelivery as 'payer' | 'each' } });
+  }
+
+  // Bundle deals, then the coupon (or re-work an existing one over the merged items).
+  let couponError: string | null = null;
+  await coupons.recalculateRegistrationDiscount(registrationId);
+  if (couponCode) {
+    try {
+      await coupons.applyCouponToRegistration({ registrationId, code: couponCode });
+    } catch (e: any) {
+      // Lost a race for the last use since the check above — keep the registration.
+      if (!e.isCouponError) throw e;
+      couponError = e.message;
+    }
+  }
+  const load = () => prisma.registration.findUniqueOrThrow({
+    where: { id: registrationId },
+    include: { ...FULL_INCLUDE, couponRedemptions: ACTIVE_COUPONS_INCLUDE, bundleApplications: BUNDLE_APPS_INCLUDE, attendees: ATTENDEES_INCLUDE },
+  });
+  let registration = await load();
+
+  // Nothing owed: mark paid and issue tickets (unless a required form comes first).
+  let emailTicketsAfter = false;
+  try {
+    if (pricing.computeRegistrationTotalDue(registration, new Date()) === 0) {
+      if (registration.status !== 'paid') {
+        await prisma.registration.update({ where: { id: registrationId }, data: { status: 'paid', updatedAt: new Date() } });
+      }
+      const form = await prisma.eventForm.findUnique({ where: { eventId: registration.eventId } }).catch(() => null);
+      if (!(form && form.isRequired)) {
+        // Same generator as paid registrations: a ticket per named attendee, and one
+        // shared quantity ticket for the rest of each line.
+        await generateTicketsForRegistration(registrationId);
+        emailTicketsAfter = true;
+      }
+      registration = { ...registration, status: 'paid' };
+    }
+  } catch {
+    // ignore errors in auto-generation path; manual generation remains available
+  }
+
+  // Fire-and-forget: registration email first, then tickets (guarantees order)
+  const notifications = require('../utils/notifications') as { sendRegistrationEmails(id: string): Promise<unknown>; sendRegistrationUpdatedEmails(id: string): Promise<unknown> };
+  const ownerId = registration.userId;
+  void (async () => {
+    try {
+      if (isNewRegistration) await notifications.sendRegistrationEmails(registrationId);
+      else await notifications.sendRegistrationUpdatedEmails(registrationId);
+    } catch (e) { console.error('Failed to send registration emails:', e); }
+    if (emailTicketsAfter) {
+      try {
+        const { emailTickets } = require('../controllers/ticketController') as { emailTickets(req: unknown, res: unknown): Promise<unknown> };
+        const res: { status(): unknown; json(): void } = { status: () => res, json: () => {} };
+        await emailTickets({ user: { id: ownerId }, body: { registrationId } }, res);
+      } catch (e) { console.error('Error emailing tickets for free registration:', e); }
+    }
+  })();
+
+  // Funnel: this registration came from a tracked (cookie-consented) visit.
+  if (analyticsSessionId) {
+    const { recordSubmit } = require('../utils/analytics') as { recordSubmit(reg: unknown, sessionId: string): Promise<unknown> };
+    recordSubmit(registration, analyticsSessionId).catch((e: any) => console.warn('[analytics] submit not recorded:', e?.message || e));
+  }
+
+  return { registration: pricing.attachComputedTotals(registration), isNew: isNewRegistration, couponError };
+}
+
+/**
+ * Cancels a registration: the owner (not after the event, not once anything is paid) or an
+ * admin. Releases its coupon and offers its places to the waitlist.
+ */
+export async function cancelRegistration(registrationId: string, actor: { id: string; role: Role }, ip?: string) {
+  const registration = await prisma.registration.findUnique({
+    where: { id: registrationId },
+    include: { event: { select: { endDate: true } } },
+  });
+  if (!registration) return fail(404, 'Registration not found');
+
+  if (registration.userId !== actor.id && actor.role !== 'admin') fail(403, 'Not authorized to cancel this registration');
+
+  // If event is in the past, block self-cancellation (mirrors the edit block)
+  if (actor.role !== 'admin' && registration.event?.endDate && new Date(registration.event.endDate).getTime() < Date.now()) {
+    fail(400, 'This event has already ended; registration can no longer be cancelled');
+  }
+
+  try {
+    await assertEventOpen(registration.eventId);
+  } catch (e: any) {
+    throw new ServiceError(e.message === 'Event not found' ? 404 : 400, e.message);
+  }
+
+  if (registration.status === 'cancelled') fail(400, 'Registration is already cancelled');
+
+  // Non-admins cannot cancel a registration that has payments against it
+  if (actor.role !== 'admin') {
+    const paymentCount = await prisma.payment.count({ where: { registrationId: registration.id, amount: { gt: 0 } } });
+    if (paymentCount > 0) fail(403, 'This registration has payments recorded against it and cannot be self-cancelled. Please contact the organisation for assistance.');
+  }
+
+  const updated = await prisma.registration.update({ where: { id: registrationId }, data: { status: 'cancelled', updatedAt: new Date() } });
+  await coupons.releaseRegistrationCoupons(registrationId);
+  waitlist.queueWaitlist(registration.eventId);
+
+  // Only log when staff cancels on someone else's behalf — a routine self-service
+  // cancellation isn't an admin action worth cluttering the audit trail with.
+  if (registration.userId !== actor.id) {
+    logAdminAction({
+      actorId: actor.id, actorRole: actor.role, action: 'registration_cancelled', targetType: 'Registration', targetId: registrationId,
+      metadata: { registrationOwnerId: registration.userId }, ip,
+    });
+  }
+  return updated;
+}

backend/src/services/setup.ts

@@ -0,0 +1,140 @@
+/**
+ * Scanning sections and planned event costs (1.51.8). Moved from sectionController.js and
+ * costController.js so v1 and /api/v2 share them.
+ */
+import { v4 as uuidv4 } from 'uuid';
+import { prisma } from '../v2/legacy';
+import { fail } from './errors';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- the JS helpers below aren't typed yet */
+const cashup = require('../utils/cashupUtils') as { assertEventOpen(eventId: string): Promise<unknown>; ALL_METHODS: string[] };
+
+const openEvent = async (eventId: string) => {
+  try {
+    await cashup.assertEventOpen(eventId);
+  } catch (e: any) {
+    fail(e.message === 'Event not found' ? 404 : 400, e.message);
+  }
+};
+
+// ─── Sections (which ticket types may come in at which door) ─────────────────
+
+const SECTION_INCLUDE = { allowedOptions: { include: { eventOption: true } } } as const;
+
+/** Sections, for one event or every event the caller may see (`scopeWhere` from campus scope). */
+export function listSections(eventId: string | undefined, scopeWhere: object) {
+  const where = { AND: [eventId && eventId !== 'all' ? { eventId } : {}, scopeWhere] };
+  return prisma.section.findMany({ where, include: { ...SECTION_INCLUDE, event: { select: { id: true, title: true } } }, orderBy: { name: 'asc' } });
+}
+
+export async function createSection(input: { eventId?: string; name?: string; allowedOptionIds?: string[] }) {
+  if (!input.eventId || !input.name) return fail(400, 'Event and section name are required');
+  const event = await prisma.event.findUnique({ where: { id: input.eventId }, select: { id: true } });
+  if (!event) return fail(404, 'Event not found');
+  const section = await prisma.section.create({ data: { id: uuidv4(), eventId: input.eventId, name: String(input.name), updatedAt: new Date() } });
+  if (Array.isArray(input.allowedOptionIds) && input.allowedOptionIds.length > 0) {
+    await prisma.sectionOption.createMany({
+      data: input.allowedOptionIds.map(optionId => ({ id: uuidv4(), sectionId: section.id, eventOptionId: optionId })),
+      skipDuplicates: true,
+    });
+  }
+  return prisma.section.findUniqueOrThrow({ where: { id: section.id }, include: SECTION_INCLUDE });
+}
+
+/** Renames a section and/or replaces its ticket types (when `allowedOptionIds` is sent). */
+export async function updateSection(sectionId: string, input: { name?: string; allowedOptionIds?: string[] }) {
+  const section = await prisma.section.findUnique({ where: { id: sectionId } });
+  if (!section) return fail(404, 'Section not found');
+  await prisma.section.update({ where: { id: sectionId }, data: { name: input.name || section.name, updatedAt: new Date() } });
+  if (Array.isArray(input.allowedOptionIds)) {
+    await prisma.sectionOption.deleteMany({ where: { sectionId } });
+    if (input.allowedOptionIds.length > 0) {
+      await prisma.sectionOption.createMany({ data: input.allowedOptionIds.map(optionId => ({ id: uuidv4(), sectionId, eventOptionId: optionId })) });
+    }
+  }
+  return prisma.section.findUniqueOrThrow({ where: { id: sectionId }, include: SECTION_INCLUDE });
+}
+
+export async function deleteSection(sectionId: string) {
+  const section = await prisma.section.findUnique({ where: { id: sectionId }, select: { id: true } });
+  if (!section) return fail(404, 'Section not found');
+  await prisma.section.delete({ where: { id: sectionId } });
+}
+
+// ─── Planned costs (for cashup and the profit report) ────────────────────────
+
+const COST_INCLUDE = { eventOption: { select: { id: true, name: true } } } as const;
+
+function paidFromMethod(value: unknown): string | null | undefined {
+  if (value === undefined) return undefined;
+  if (value === null || value === '') return null;
+  if (!cashup.ALL_METHODS.includes(String(value))) fail(400, "paidFromMethod must be one of 'cash', 'card', 'eft', 'other', or null");
+  return String(value);
+}
+
+export function listCosts(eventId: string) {
+  return prisma.eventCost.findMany({ where: { eventId }, include: COST_INCLUDE, orderBy: { createdAt: 'asc' } });
+}
+
+export type CostInput = { label?: string; costType?: string; amount?: number | string; eventOptionId?: string | null; notes?: string | null; paidFromMethod?: string | null };
+
+/** A cost per event ("hall hire") or per ticket sold ("T-shirt per camper"). */
+export async function createCost(eventId: string, input: CostInput) {
+  await openEvent(eventId);
+  if (!input.label || !String(input.label).trim()) fail(400, 'Label is required');
+  if (input.costType !== 'once_off' && input.costType !== 'per_item') fail(400, "costType must be 'once_off' or 'per_item'");
+  const amount = parseFloat(String(input.amount));
+  if (!(amount >= 0)) fail(400, 'Amount must be a non-negative number');
+  if (input.costType === 'per_item') {
+    if (!input.eventOptionId) fail(400, 'eventOptionId is required for per-item costs');
+    const option = await prisma.eventOption.findUnique({ where: { id: input.eventOptionId! }, select: { eventId: true } });
+    if (!option || option.eventId !== eventId) fail(404, 'Ticket type not found for this event');
+  }
+  return prisma.eventCost.create({
+    data: {
+      id: uuidv4(), eventId, label: String(input.label).trim(), costType: input.costType as 'once_off' | 'per_item', amount,
+      eventOptionId: input.costType === 'per_item' ? input.eventOptionId! : null,
+      paidFromMethod: (paidFromMethod(input.paidFromMethod) ?? null) as any, notes: input.notes || null,
+    },
+    include: COST_INCLUDE,
+  });
+}
+
+export async function updateCost(costId: string, input: CostInput) {
+  const existing = await prisma.eventCost.findUnique({ where: { id: costId } });
+  if (!existing) return fail(404, 'Cost not found');
+  await openEvent(existing.eventId);
+  const costType = input.costType !== undefined ? input.costType : existing.costType;
+  if (costType !== 'once_off' && costType !== 'per_item') fail(400, "costType must be 'once_off' or 'per_item'");
+  const eventOptionId = costType === 'per_item' ? (input.eventOptionId !== undefined ? input.eventOptionId : existing.eventOptionId) : null;
+  if (costType === 'per_item') {
+    if (!eventOptionId) fail(400, 'eventOptionId is required for per-item costs');
+    const option = await prisma.eventOption.findUnique({ where: { id: eventOptionId! }, select: { eventId: true } });
+    if (!option || option.eventId !== existing.eventId) fail(404, 'Ticket type not found for this event');
+  }
+  let amount = existing.amount;
+  if (input.amount !== undefined) {
+    amount = parseFloat(String(input.amount));
+    if (!(amount >= 0)) fail(400, 'Amount must be a non-negative number');
+  }
+  const paid = paidFromMethod(input.paidFromMethod);
+  return prisma.eventCost.update({
+    where: { id: costId },
+    data: {
+      label: input.label !== undefined ? String(input.label).trim() : existing.label,
+      costType: costType as 'once_off' | 'per_item',
+      amount,
+      eventOptionId,
+      paidFromMethod: (paid !== undefined ? paid : existing.paidFromMethod) as any,
+      notes: input.notes !== undefined ? input.notes : existing.notes,
+    },
+    include: COST_INCLUDE,
+  });
+}
+
+export async function deleteCost(costId: string) {
+  const existing = await prisma.eventCost.findUnique({ where: { id: costId }, select: { eventId: true } });
+  if (!existing) return fail(404, 'Cost not found');
+  await openEvent(existing.eventId);
+  await prisma.eventCost.delete({ where: { id: costId } });
+}

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',
 };
 
 /**

backend/src/utils/adminAudit.js

@@ -21,16 +21,44 @@ async function logAdminAction({ actorId, actorRole, action, targetType, targetId
   }
 }
 
-// Paginated listing for the admin audit-log page, with optional actor/action/date filters.
-async function getAdminAuditLog({ page = 1, limit = 50, actorId, action, from, to } = {}) {
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const DAY_MS = 24 * 60 * 60 * 1000;
+// A date (YYYY-MM-DD) means midnight in the server's time zone (APP_TIMEZONE), not UTC.
+const startOf = (v) => new Date(DATE_ONLY.test(v) ? `${v}T00:00:00` : v);
+
+// The Prisma filter for the audit-log page. Dates (YYYY-MM-DD) are whole days, so `to`
+// includes that day. `search` matches the person (name or email), the target type or id,
+// or the IP.
+function auditLogWhere({ actorId, action, role, from, to, search } = {}) {
   const where = {};
   if (actorId) where.actorId = actorId;
   if (action) where.action = action;
+  if (role) where.actorRole = role;
   if (from || to) {
     where.createdAt = {};
-    if (from) where.createdAt.gte = new Date(from);
-    if (to) where.createdAt.lte = new Date(to);
+    if (from) where.createdAt.gte = startOf(from);
+    if (to) {
+      if (DATE_ONLY.test(to)) where.createdAt.lt = new Date(startOf(to).getTime() + DAY_MS);
+      else where.createdAt.lte = new Date(to);
+    }
   }
+  const q = String(search || '').trim().slice(0, 100);
+  if (q) {
+    const contains = { contains: q, mode: 'insensitive' };
+    where.OR = [
+      { actor: { name: contains } },
+      { actor: { email: contains } },
+      { targetType: contains },
+      { targetId: { startsWith: q.replace(/^#/, '') } },
+      { ip: { startsWith: q } },
+    ];
+  }
+  return where;
+}
+
+// Paginated listing for the admin audit-log page.
+async function getAdminAuditLog({ page = 1, limit = 50, ...filters } = {}) {
+  const where = auditLogWhere(filters);
 
   const take = Math.min(Math.max(Number(limit) || 50, 1), 200);
   const skip = (Math.max(Number(page) || 1, 1) - 1) * take;
@@ -49,4 +77,4 @@ async function getAdminAuditLog({ page = 1, limit = 50, actorId, action, from, t
   return { rows, total, page: Math.max(Number(page) || 1, 1), limit: take };
 }
 
-module.exports = { logAdminAction, getAdminAuditLog };
+module.exports = { logAdminAction, getAdminAuditLog, auditLogWhere };

backend/src/utils/bulkRegistrations.js

@@ -0,0 +1,192 @@
+/**
+ * Bulk actions on registrations (1.49.1): the registrations list lets a supervisor or admin tick
+ * many and act on them at once — mark paid, cancel, move to another ticket, put in a room or
+ * group, or send a message.
+ *
+ * Each action runs the same code as doing it one at a time (the controllers' own handlers, called
+ * in-process), so every rule still applies: closed events, payment caps and overpayments becoming
+ * donations, tickets and emails on payment, coupons released and the waitlist offered on
+ * cancelling, pricing on a ticket change, room capacity and gender, and the privacy rules and
+ * footers on messages. Results come back per registration; one failing doesn't stop the rest.
+ */
+
+const prisma = require('../config/db');
+
+const MAX = 500;
+const ACTIONS = ['markPaid', 'cancel', 'moveOption', 'allocate', 'message'];
+const METHODS = ['cash', 'eft', 'card', 'other'];
+
+function bulkError(message, statusCode = 400) {
+  const err = new Error(message);
+  err.statusCode = statusCode;
+  return err;
+}
+
+/** Calls an Express handler in-process; resolves to { ok, status, body }. */
+function call(handler, req) {
+  return new Promise((resolve) => {
+    const res = {
+      statusCode: 200,
+      status(code) { this.statusCode = code; return this; },
+      json(body) { resolve({ ok: this.statusCode < 400, status: this.statusCode, body }); return this; },
+      send(body) { resolve({ ok: this.statusCode < 400, status: this.statusCode, body }); return this; },
+    };
+    Promise.resolve(handler({ query: {}, params: {}, body: {}, headers: {}, ip: req.ip, ...req }, res))
+      .catch(e => resolve({ ok: false, status: 500, body: { message: e?.message || String(e) } }));
+  });
+}
+
+/** Who is asking, with their request's headers and socket (so audit entries keep the real IP). */
+const from = req => ({ user: req.user, headers: req.headers || {}, socket: req.socket });
+
+const messageOf = r => r.body?.message || (r.ok ? 'Done' : `Failed (${r.status})`);
+
+async function markPaid(req, regs, { method, paidAt }) {
+  if (!METHODS.includes(method)) throw bulkError('Choose how it was paid (cash, EFT, card or other)');
+  const { createPayment } = require('../controllers/paymentController');
+  const { refreshPricingForRegistration, computeRegistrationTotalDue } = require('./pricing');
+  const out = [];
+  for (const r of regs) {
+    if (r.status === 'cancelled') { out.push({ id: r.id, ok: false, message: 'Cancelled — not paid' }); continue; }
+    try { await refreshPricingForRegistration(r.id); } catch { /* the payment code refreshes too */ }
+    const fresh = await prisma.registration.findUnique({ where: { id: r.id }, include: { registrationOptions: { include: { eventOption: { include: { earlyBirdTiers: true } }, tranches: true } }, payments: true } });
+    const owed = Math.round((computeRegistrationTotalDue(fresh, new Date()) - fresh.payments.reduce((s, p) => s + p.amount, 0)) * 100) / 100;
+    if (owed <= 0) { out.push({ id: r.id, ok: true, skipped: true, message: 'Already paid' }); continue; }
+    const res = await call(createPayment, { ...from(req), body: { amount: owed, method, registrationId: r.id, userId: r.userId, ...(paidAt ? { paidAt } : {}) } });
+    out.push({ id: r.id, ok: res.ok, message: res.ok ? `R${owed.toFixed(2)} recorded` : messageOf(res) });
+  }
+  return out;
+}
+
+async function cancel(req, regs) {
+  const { cancelRegistration } = require('../controllers/registrationController');
+  const out = [];
+  for (const r of regs) {
+    if (r.status === 'cancelled') { out.push({ id: r.id, ok: true, skipped: true, message: 'Already cancelled' }); continue; }
+    const res = await call(cancelRegistration, { ...from(req), params: { id: r.id } });
+    out.push({ id: r.id, ok: res.ok, message: res.ok ? 'Cancelled' : messageOf(res) });
+  }
+  return out;
+}
+
+/**
+ * Moves every place on `fromOptionId` to `toOptionId`, keeping the same lines, tickets (and their
+ * QR codes) and named people — the editing screen can't take issued tickets away, but a move
+ * doesn't need to. Each moved line is repriced at the new ticket's current price (early birds and
+ * staff prices as for a new registration); the status follows what's now paid against owed, so
+ * moving up shows the difference owing and moving down shows the overpayment. Places on the new
+ * ticket are checked first.
+ */
+async function moveOption(req, regs, { fromOptionId, toOptionId }) {
+  if (!fromOptionId || !toOptionId || fromOptionId === toOptionId) throw bulkError('Choose the ticket to move from and the one to move to');
+  const options = await prisma.eventOption.findMany({ where: { id: { in: [fromOptionId, toOptionId] } }, include: { earlyBirdTiers: true, event: { select: { id: true, cashupStatus: true, kidsOptionId: true, volunteerOptionId: true } } } });
+  if (options.length !== 2 || options[0].eventId !== options[1].eventId) throw bulkError('Both tickets must belong to the same event');
+  const target = options.find(o => o.id === toOptionId);
+  const event = target.event;
+  if (event.cashupStatus === 'closed') throw bulkError('This event is closed. Reopen it (admin only) before making changes.');
+  if ([event.kidsOptionId, event.volunteerOptionId].includes(toOptionId)) throw bulkError('The kids and volunteer tickets are handed out by staff, not moved to');
+  const { resolveOptionPrice } = require('./pricing');
+  const { remainingFor } = require('./stock');
+  const { updateRegistrationStatus } = require('../payments/webhook');
+  const out = [];
+  for (const r of regs) {
+    if (r.eventId !== event.id) { out.push({ id: r.id, ok: false, message: 'Not for this event' }); continue; }
+    if (r.status === 'cancelled') { out.push({ id: r.id, ok: false, message: 'Cancelled' }); continue; }
+    if (r.seasonPassPurchaseId) { out.push({ id: r.id, ok: false, message: 'Part of a season pass — tickets can\'t be changed' }); continue; }
+    const lines = await prisma.registrationOption.findMany({ where: { registrationId: r.id, eventOptionId: fromOptionId, sessionId: null }, select: { id: true, quantity: true } });
+    if (!lines.length) { out.push({ id: r.id, ok: true, skipped: true, message: 'No such ticket to move' }); continue; }
+    const qty = lines.reduce((s, l) => s + l.quantity, 0);
+    const left = await remainingFor(target, null);
+    if (left !== null && left < qty) { out.push({ id: r.id, ok: false, message: `Only ${left} place${left === 1 ? '' : 's'} left on ${target.name}` }); continue; }
+    try {
+      const owner = await prisma.user.findUnique({ where: { id: r.userId }, select: { role: true } });
+      const { price, tierId } = await resolveOptionPrice(target, qty, owner);
+      await prisma.$transaction(async tx => {
+        for (const line of lines) {
+          await tx.registrationOption.update({ where: { id: line.id }, data: { eventOptionId: toOptionId, variantId: null, priceSnapshot: price, appliedTierId: tierId || null } });
+          await tx.registrationOptionTranche.deleteMany({ where: { registrationOptionId: line.id } });
+          await tx.registrationOptionTranche.create({ data: { registrationOptionId: line.id, quantity: line.quantity, priceSnapshot: price, appliedTierId: tierId || null } });
+          await tx.attendee.updateMany({ where: { registrationOptionId: line.id }, data: { eventOptionId: toOptionId, variantId: null } });
+        }
+      });
+      const updated = await updateRegistrationStatus(r.id);
+      const diff = Math.round(((updated.totalDue || 0) - (updated.totalPaid || 0)) * 100) / 100;
+      out.push({ id: r.id, ok: true, message: diff > 0 ? `Moved — R${diff.toFixed(2)} now owing` : diff < 0 ? `Moved — R${(-diff).toFixed(2)} overpaid` : 'Moved' });
+    } catch (e) {
+      out.push({ id: r.id, ok: false, message: e?.message || 'Couldn\'t move' });
+    }
+  }
+  return out;
+}
+
+async function allocate(req, regs, { setId, groupId }) {
+  if (!setId || !groupId) throw bulkError('Choose the group to put them in');
+  const { assign } = require('../controllers/allocationController');
+  const out = [];
+  for (const r of regs) {
+    const people = await prisma.attendee.findMany({ where: { registrationId: r.id }, select: { id: true, name: true } });
+    if (!people.length) { out.push({ id: r.id, ok: false, message: 'No named people on this registration to place' }); continue; }
+    const fails = [];
+    for (const a of people) {
+      const res = await call(assign, { ...from(req), params: { id: setId }, body: { attendeeId: a.id, groupId } });
+      if (!res.ok) fails.push(`${a.name}: ${messageOf(res)}`);
+    }
+    out.push({ id: r.id, ok: fails.length === 0, message: fails.length ? fails.join('; ') : `${people.length} placed` });
+  }
+  return out;
+}
+
+async function message(req, regs, { channel, subject, text }) {
+  if (!['email', 'whatsapp'].includes(channel)) throw bulkError('Choose email or WhatsApp');
+  if (!String(text || '').trim()) throw bulkError('Write the message');
+  if (channel === 'email' && !String(subject || '').trim()) throw bulkError('Give the email a subject');
+  const { emailEventAttendees, whatsappEventAttendees } = require('../controllers/eventController');
+  const byEvent = new Map();
+  for (const r of regs) byEvent.set(r.eventId, [...(byEvent.get(r.eventId) || []), r.id]);
+  const out = [];
+  for (const [eventId, ids] of byEvent) {
+    // An event update to the people ticked (they registered, so it goes even to those who opted out of news).
+    const body = channel === 'email'
+      ? { subject, text, kind: 'update', filter: { registrationIds: ids } }
+      : { message: text, kind: 'update', filter: { registrationIds: ids } };
+    const res = await call(channel === 'email' ? emailEventAttendees : whatsappEventAttendees, { ...from(req), params: { id: eventId }, body });
+    for (const id of ids) out.push({ id, ok: res.ok, message: res.ok ? `Sent with ${res.body?.sent ?? res.body?.matched ?? ids.length} for this event` : messageOf(res) });
+  }
+  return out;
+}
+
+/**
+ * Runs one bulk action. Returns { action, done, skipped, failed, results: [{ id, ok, skipped?, message }] }.
+ */
+async function runBulk(req, { action, registrationIds, ...params }) {
+  if (!ACTIONS.includes(action)) throw bulkError('Unknown bulk action');
+  const ids = [...new Set((Array.isArray(registrationIds) ? registrationIds : []).map(String))];
+  if (!ids.length) throw bulkError('Tick at least one registration');
+  if (ids.length > MAX) throw bulkError(`At most ${MAX} at a time`);
+  // Read-only licence: no new payments or ticket changes (cancelling and messaging still work).
+  if (['markPaid', 'moveOption'].includes(action)) {
+    const { licenceStatus } = require('../hub/licence');
+    const status = await licenceStatus().catch(() => null);
+    if (status?.readOnly) throw bulkError('This site is read-only (licence), so payments and ticket changes can\'t be recorded.', 403);
+  }
+  const regs = await prisma.registration.findMany({ where: { id: { in: ids } }, include: { registrationOptions: { select: { eventOptionId: true, variantId: true, quantity: true, sessionId: true } } } });
+  const missing = ids.filter(id => !regs.some(r => r.id === id)).map(id => ({ id, ok: false, message: 'Not found' }));
+  const run = { markPaid, cancel, moveOption, allocate, message }[action];
+  const results = [...missing, ...(await run(req, regs, params))];
+  const { logAdminAction } = require('./adminAudit');
+  const { getClientIp } = require('./requestUtils');
+  logAdminAction({
+    actorId: req.user.id, actorRole: req.user.role, action: 'registrations_bulk', targetType: 'Registration',
+    metadata: { bulk: action, registrations: ids.length, done: results.filter(r => r.ok && !r.skipped).length, failed: results.filter(r => !r.ok).length },
+    ip: getClientIp({ headers: {}, ...req }),
+  });
+  return {
+    action,
+    done: results.filter(r => r.ok && !r.skipped).length,
+    skipped: results.filter(r => r.skipped).length,
+    failed: results.filter(r => !r.ok).length,
+    results,
+  };
+}
+
+module.exports = { runBulk, ACTIONS, MAX };

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. */

backend/src/utils/dashboard.js

@@ -0,0 +1,249 @@
+/**
+ * The home dashboard for staff, supervisors and admins (1.49.0): what's on today, money in, and
+ * what's waiting for someone — plus the search behind the Ctrl+K command palette.
+ *
+ * Everything follows the person's campus scope (utils/campusScope.js): a campus-limited
+ * supervisor sees their campuses' events and church-wide ones. Items only some roles can act on
+ * (cashups, provider payments, privacy requests, webhooks) are shown to those roles only.
+ */
+
+const prisma = require('../config/db');
+const { scopeFor, eventWhere } = require('./campusScope');
+
+const DAY = 864e5;
+// The same "real money" as the dashboards: everything except legs that apply an earlier donation.
+const EXCLUDE_DONATION_LEGS = { NOT: { AND: [{ isDonation: false }, { originalPaymentId: { not: null } }, { amount: { gt: 0 } }] } };
+
+function dayBounds(now = new Date()) {
+  const start = new Date(now); start.setHours(0, 0, 0, 0);
+  return { start, end: new Date(start.getTime() + DAY - 1) };
+}
+
+const isAdmin = req => req.user?.role === 'admin';
+const isSupervisor = req => ['admin', 'supervisor'].includes(req.user?.role);
+
+/** Events on today (single-date events running today, or a session today), with how it's going. */
+async function todaysEvents(scopeWhere, now = new Date()) {
+  const { start, end } = dayBounds(now);
+  const events = await prisma.event.findMany({
+    where: {
+      AND: [scopeWhere, { isActive: true }, {
+        OR: [
+          { scheduleType: 'single', startDate: { lte: end }, endDate: { gte: start } },
+          { scheduleType: 'sessions', sessions: { some: { startsAt: { gte: start, lte: end }, cancelledAt: null } } },
+        ],
+      }],
+    },
+    orderBy: { startDate: 'asc' },
+    select: {
+      id: true, title: true, startDate: true, endDate: true, location: true, scheduleType: true, kidsCheckIn: true, isHidden: true,
+      campus: { select: { id: true, name: true, slug: true, colour: true } },
+      sessions: { where: { startsAt: { gte: start, lte: end }, cancelledAt: null }, orderBy: { startsAt: 'asc' }, select: { id: true, label: true, startsAt: true, endsAt: true } },
+    },
+  });
+  return Promise.all(events.map(async e => {
+    const session = e.sessions[0] || null;
+    const [places, scans, kidsIn, roles] = await Promise.all([
+      prisma.ticket.aggregate({ where: { eventId: e.id, registrationOption: { registration: { status: { not: 'cancelled' } } } }, _sum: { quantity: true } }),
+      prisma.ticketUsage.aggregate({ where: { ticket: { eventId: e.id }, scannedAt: { gte: start, lte: end } }, _sum: { quantityRedeemed: true } }),
+      e.kidsCheckIn ? prisma.kidsCheckIn.count({ where: { eventId: e.id, checkedOutAt: null, checkedInAt: { gte: start, lte: end } } }) : Promise.resolve(null),
+      prisma.servingRole.findMany({
+        where: { eventId: e.id, OR: [{ sessionId: null }, ...(session ? [{ sessionId: session.id }] : [])] },
+        select: { needed: true, slots: { select: { checkedInAt: true } } },
+      }),
+    ]);
+    return {
+      id: e.id, title: e.title, location: e.location, campus: e.campus, isHidden: e.isHidden, kidsCheckIn: e.kidsCheckIn,
+      startsAt: session ? session.startsAt : e.startDate, endsAt: session ? session.endsAt : e.endDate,
+      sessionLabel: session ? session.label : null,
+      places: places._sum.quantity || 0,
+      checkedIn: scans._sum.quantityRedeemed || 0,
+      kidsIn,
+      volunteers: roles.length ? {
+        needed: roles.reduce((s, r) => s + r.needed, 0),
+        rostered: roles.reduce((s, r) => s + r.slots.length, 0),
+        checkedIn: roles.reduce((s, r) => s + r.slots.filter(x => x.checkedInAt).length, 0),
+      } : null,
+    };
+  }));
+}
+
+/** Money in today and over the last 7 days (the person's events, or everything for the unscoped). */
+async function moneyIn(scope, now = new Date()) {
+  const { start } = dayBounds(now);
+  const weekStart = new Date(start.getTime() - 6 * DAY);
+  const where = from => ({ ...EXCLUDE_DONATION_LEGS, createdAt: { gte: from }, ...(scope ? { event: eventWhere(scope) } : {}) });
+  const [today, week] = await Promise.all([
+    prisma.payment.aggregate({ where: where(start), _sum: { amount: true }, _count: { _all: true } }),
+    prisma.payment.aggregate({ where: where(weekStart), _sum: { amount: true } }),
+  ]);
+  return { today: today._sum.amount || 0, todayCount: today._count._all, week: week._sum.amount || 0 };
+}
+
+/**
+ * What's waiting for someone: each { key, label, count, href, tone }, only those with a count.
+ * `href` takes the person to where it's dealt with.
+ */
+async function pendingItems(req, scope, now = new Date()) {
+  const upcoming = { startDate: { gte: now } };
+  const scoped = (extra = {}) => ({ AND: [eventWhere(scope), extra] });
+  const soon = new Date(now.getTime() + 14 * DAY);
+  const week = new Date(now.getTime() + 7 * DAY);
+  const items = [];
+  const push = async (key, fn) => {
+    try {
+      const item = await fn();
+      if (item && item.count > 0) items.push({ key, ...item });
+    } catch (e) {
+      console.warn(`[dashboard] ${key}:`, e?.message || e);
+    }
+  };
+
+  await Promise.all([
+    push('unpaid', async () => ({
+      label: 'Unpaid or part-paid registrations for events in the next two weeks',
+      count: await prisma.registration.count({ where: { status: { in: ['pending', 'partial_paid'] }, event: scoped({ startDate: { gte: now, lte: soon }, isActive: true }) } }),
+      href: isAdmin(req) ? '/dashboard/admin/registrations?status=pending' : '/dashboard/supervisor/reports?report=regStatus',
+      tone: 'amber',
+    })),
+    push('consent', async () => {
+      const pending = await prisma.consentRequest.findMany({ where: { status: 'pending', event: scoped(upcoming) }, select: { attendeeId: true }, distinct: ['attendeeId'] });
+      const given = new Set((await prisma.consentRequest.findMany({ where: { status: 'given', attendeeId: { in: pending.map(p => p.attendeeId) } }, select: { attendeeId: true } })).map(g => g.attendeeId));
+      return { label: 'Young people still waiting for parental consent', count: pending.filter(p => !given.has(p.attendeeId)).length, href: '/dashboard/supervisor/consent', tone: 'rose' };
+    }),
+    push('waitlist', async () => ({
+      label: 'People on a waitlist',
+      count: await prisma.waitlistEntry.count({ where: { status: 'waiting', event: scoped(upcoming) } }),
+      href: '/dashboard/supervisor/waitlist',
+      tone: 'blue',
+    })),
+    push('cover', async () => ({
+      label: 'Volunteers asking for someone to cover their shift',
+      count: await prisma.volunteerSwap.count({ where: { status: 'open', role: { event: scoped({ endDate: { gte: now } }) } } }),
+      href: '/dashboard/supervisor/volunteers',
+      tone: 'violet',
+    })),
+    push('roster', async () => {
+      const roles = await prisma.servingRole.findMany({
+        where: {
+          event: scoped({ isActive: true }),
+          OR: [{ session: { startsAt: { gte: now, lte: week } } }, { sessionId: null, event: { startDate: { gte: now, lte: week } } }],
+        },
+        select: { needed: true, _count: { select: { slots: true } } },
+      });
+      return { label: 'Serving roles in the next week that still need people', count: roles.filter(r => r._count.slots < r.needed).length, href: '/dashboard/supervisor/volunteers', tone: 'violet' };
+    }),
+    isAdmin(req) && push('cashup', async () => ({
+      label: 'Past events still to cash up',
+      count: await prisma.event.count({ where: { cashupStatus: 'open', endDate: { lt: new Date(now.getTime() - DAY), gte: new Date(now.getTime() - 120 * DAY) }, payments: { some: {} } } }),
+      href: '/dashboard/admin/cashup',
+      tone: 'green',
+    })),
+    (isAdmin(req) || (isSupervisor(req) && !scope)) && push('reconcile', async () => ({
+      label: 'Online payments that didn\'t match a registration (reconcile them)',
+      count: await prisma.providerTransaction.count({ where: { reconciled: false, ignored: false } }),
+      href: '/dashboard/supervisor/payments',
+      tone: 'amber',
+    })),
+    isAdmin(req) && push('privacy', async () => ({
+      label: 'Privacy requests to answer',
+      count: await prisma.dataRequest.count({ where: { status: 'open' } }),
+      href: '/dashboard/admin/data-requests',
+      tone: 'rose',
+    })),
+    isAdmin(req) && push('webhooks', async () => ({
+      label: 'Webhook deliveries that failed this week',
+      count: await prisma.webhookDelivery.count({ where: { status: 'failed', createdAt: { gte: new Date(now.getTime() - 7 * DAY) } } }),
+      href: '/dashboard/admin/settings?tab=webhooks',
+      tone: 'rose',
+    })),
+  ].filter(Boolean));
+  const order = ['privacy', 'consent', 'unpaid', 'cover', 'roster', 'waitlist', 'reconcile', 'cashup', 'webhooks'];
+  return items.sort((a, b) => order.indexOf(a.key) - order.indexOf(b.key));
+}
+
+async function today(req, now = new Date()) {
+  const scope = await scopeFor(req);
+  const [events, money, pending] = await Promise.all([
+    todaysEvents(eventWhere(scope), now),
+    isSupervisor(req) ? moneyIn(scope, now) : Promise.resolve(null),
+    isSupervisor(req) ? pendingItems(req, scope, now) : Promise.resolve([]),
+  ]);
+  return { events, money, pending };
+}
+
+// ─── Command palette search ──────────────────────────────────────────────────
+
+/** "R450", "450", "r 450.50" → 450.5; anything else → null. Pure. */
+function amountOf(q) {
+  const m = /^r?\s*(\d{1,7}(?:[.,]\d{1,2})?)$/i.exec(String(q || '').trim());
+  return m ? parseFloat(m[1].replace(',', '.')) : null;
+}
+
+/**
+ * Results for the command palette: events (everyone with dashboard access), and for supervisors
+ * payments by amount ("R450"); for admins also people and registrations. Each { type, id, title,
+ * subtitle, href }. Up to 5 of each kind.
+ */
+async function search(req, rawQuery, now = new Date()) {
+  const q = String(rawQuery || '').trim().slice(0, 80);
+  if (q.length < 2) return [];
+  const scope = await scopeFor(req);
+  const contains = { contains: q, mode: 'insensitive' };
+  const out = [];
+  const supervisor = isSupervisor(req);
+  const fmtDate = d => new Date(d).toLocaleDateString('en-ZA', { day: 'numeric', month: 'short', year: 'numeric' });
+
+  const events = await prisma.event.findMany({
+    where: { AND: [eventWhere(scope), { title: contains }] },
+    orderBy: { startDate: 'desc' }, take: 5,
+    select: { id: true, title: true, startDate: true, isActive: true, campus: { select: { name: true } } },
+  });
+  for (const e of events) {
+    out.push({
+      type: 'event', id: e.id, title: e.title,
+      subtitle: [fmtDate(e.startDate), e.campus?.name, e.isActive ? null : 'inactive'].filter(Boolean).join(' · '),
+      href: supervisor ? `/dashboard/supervisor/events?edit=${e.id}` : `/events/${e.id}`,
+    });
+  }
+
+  const amount = amountOf(q);
+  if (supervisor && amount !== null) {
+    const payments = await prisma.payment.findMany({
+      where: { amount: { in: [amount, -amount] }, createdAt: { gte: new Date(now.getTime() - 365 * DAY) }, ...(scope ? { event: eventWhere(scope) } : {}) },
+      orderBy: { createdAt: 'desc' }, take: 5,
+      select: { id: true, amount: true, method: true, createdAt: true, registrationId: true, user: { select: { name: true } }, event: { select: { title: true } } },
+    });
+    for (const p of payments) {
+      out.push({
+        type: 'payment', id: p.id, title: `R${p.amount.toFixed(2)} — ${p.user?.name || 'Unknown'}`,
+        subtitle: [p.method, p.event?.title, fmtDate(p.createdAt)].filter(Boolean).join(' · '),
+        href: isAdmin(req) && p.registrationId ? `/dashboard/admin/registrations?q=${p.registrationId}` : '/dashboard/supervisor/payments',
+      });
+    }
+  }
+
+  if (isAdmin(req)) {
+    const people = await prisma.user.findMany({
+      where: { isActive: true, OR: [{ name: contains }, { email: contains }, { phoneNumber: { contains: q.replace(/\s+/g, '') } }] },
+      orderBy: { name: 'asc' }, take: 5,
+      select: { id: true, name: true, email: true, role: true },
+    });
+    for (const u of people) {
+      out.push({ type: 'person', id: u.id, title: u.name, subtitle: [u.email, u.role !== 'user' ? u.role : null].filter(Boolean).join(' · '), href: `/dashboard/admin/users?q=${encodeURIComponent(u.email || u.name)}` });
+    }
+    // A registration by its reference (the start of its id), as on emails and invoices.
+    if (/^[0-9a-f-]{6,36}$/i.test(q)) {
+      const regs = await prisma.registration.findMany({
+        where: { id: { startsWith: q.toLowerCase() } }, take: 5,
+        select: { id: true, status: true, user: { select: { name: true } }, event: { select: { title: true } } },
+      });
+      for (const r of regs) {
+        out.push({ type: 'registration', id: r.id, title: `Registration ${r.id.slice(0, 8)} — ${r.user?.name || ''}`.trim(), subtitle: [r.event?.title, r.status].filter(Boolean).join(' · '), href: `/dashboard/admin/registrations?q=${r.id}` });
+      }
+    }
+  }
+  return out;
+}
+
+module.exports = { today, todaysEvents, moneyIn, pendingItems, search, amountOf, dayBounds };

backend/src/utils/eventClone.js

@@ -0,0 +1,93 @@
+/**
+ * Event cloning (1.47.0). The copy itself is made by the event form in the browser — it opens
+ * "New event" filled in from the source event (details, sessions, options, variants, early-bird
+ * tiers, form, feedback form, sections, notification recipients), so everything can be changed
+ * before saving. This file copies the parts that form doesn't hold, once the new event exists:
+ * allocation sets with their groups, and (admins only) the planned costs.
+ *
+ * Never copied: registrations and everything people did, coupons, attachments, bundles, the kids
+ * check-in setup (kids ticket and rooms) and volunteer roles.
+ */
+
+const prisma = require('../config/db');
+const { v4: uuidv4 } = require('uuid');
+
+const COST_FIELDS = ['label', 'costType', 'amount', 'paidFromMethod', 'notes'];
+
+/**
+ * Costs for the new event. A cost tied to a ticket option moves to the new event's option with
+ * the same name; when there's none it stays on the event as a whole.
+ * @param {object[]} costs  the source event's EventCost rows (with `eventOption.name`)
+ * @param {object[]} newOptions  the new event's options ({ id, name })
+ */
+function costCopies(costs, newOptions) {
+  const byName = new Map(newOptions.map(o => [String(o.name).trim().toLowerCase(), o.id]));
+  return costs.map(c => {
+    const data = {};
+    for (const f of COST_FIELDS) data[f] = c[f] ?? null;
+    const name = c.eventOption?.name ? String(c.eventOption.name).trim().toLowerCase() : null;
+    data.eventOptionId = (name && byName.get(name)) || null;
+    return data;
+  });
+}
+
+/** The source's allocation sets worth copying: all but the kids rooms. */
+function setsToCopy(sets, kidsRoomSetId) {
+  return sets.filter(s => s.id !== kidsRoomSetId);
+}
+
+function cloneError(message, statusCode = 400) {
+  const err = new Error(message);
+  err.statusCode = statusCode;
+  return err;
+}
+
+/**
+ * Copies allocation sets and groups (and costs when `withCosts`) from `fromId` to the just-made
+ * event `toId`. Refused once the new event has registrations or allocation sets, so it can only
+ * fill a fresh copy.
+ * @returns {Promise<{ sets: number, groups: number, costs: number }>}
+ */
+async function copyEventSetup(fromId, toId, { withCosts = false } = {}) {
+  if (fromId === toId) throw cloneError("An event can't be copied onto itself");
+  const [from, to] = await Promise.all([
+    prisma.event.findUnique({
+      where: { id: fromId },
+      select: {
+        id: true, kidsRoomSetId: true,
+        allocationSets: { orderBy: { order: 'asc' }, include: { groups: { orderBy: { order: 'asc' } } } },
+        costs: { orderBy: { createdAt: 'asc' }, include: { eventOption: { select: { name: true } } } },
+      },
+    }),
+    prisma.event.findUnique({
+      where: { id: toId },
+      select: { id: true, eventOptions: { select: { id: true, name: true } }, _count: { select: { registrations: true, allocationSets: true } } },
+    }),
+  ]);
+  if (!from || !to) throw cloneError('Event not found', 404);
+  if (to._count.registrations > 0 || to._count.allocationSets > 0) {
+    throw cloneError('Setup can only be copied into a new event (this one already has registrations or groups)', 409);
+  }
+
+  const sets = setsToCopy(from.allocationSets, from.kidsRoomSetId);
+  const costs = withCosts ? costCopies(from.costs, to.eventOptions) : [];
+  let groups = 0;
+  await prisma.$transaction(async tx => {
+    for (const s of sets) {
+      const set = await tx.allocationSet.create({ data: { id: uuidv4(), eventId: toId, name: s.name, showOnTicket: s.showOnTicket, order: s.order } });
+      for (const g of s.groups) {
+        await tx.allocationGroup.create({
+          data: {
+            id: uuidv4(), setId: set.id, name: g.name, capacity: g.capacity, gender: g.gender,
+            leaderUserId: g.leaderUserId, order: g.order, minAge: g.minAge, maxAge: g.maxAge, ratio: g.ratio,
+          },
+        });
+        groups++;
+      }
+    }
+    for (const c of costs) await tx.eventCost.create({ data: { id: uuidv4(), eventId: toId, ...c } });
+  });
+  return { sets: sets.length, groups, costs: costs.length };
+}
+
+module.exports = { copyEventSetup, costCopies, setsToCopy };

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,
 };

backend/src/utils/notifications.js

@@ -1513,6 +1513,7 @@ async function sendAttendeeFormLinkMessage(attendee) {
 }
 
 module.exports = {
+  getEventNotifyEmails,
   buildEventNotifyRecipientList,
   sendAttendeeFormLinkMessage,
   sendRegistrationEmails,

backend/src/utils/pricing.js

@@ -211,6 +211,8 @@ async function refreshPricingForRegistration(registrationId) {
     }
   });
   if (!registration) return { changed: false };
+  // A season pass line is priced at its event's share of the pass, never at the ticket's price.
+  if (registration.seasonPassPurchaseId) return { changed: false };
 
   const totalPaid = (registration.payments || []).reduce((sum, p) => sum + (p.amount || 0), 0);
 

backend/src/utils/privacy.js

@@ -460,7 +460,17 @@ 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);
+
+    // Event series they followed.
+    await tx.seriesFollow.deleteMany({ where: { userId } });
+    // Webhook deliveries about them (kept 30 days for the delivery log).
+    await tx.webhookDelivery.deleteMany({ where: { userId } });
+    // Their saved list filters (can hold search text, such as names).
+    await tx.savedFilter.deleteMany({ where: { userId } });
+
+    return { attendees: attendeeIds.length, formAnswers: answers.count, providerRecords: txns.length + checkouts.length, familyDeleted, shiftsGivenUp };
   });
 
   await clearTrustedDevices(userId);
@@ -482,7 +492,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, seriesFollowed, seasonPasses] = await Promise.all([
     db.registration.findMany({
       where: { userId },
       orderBy: { createdAt: 'asc' },
@@ -507,6 +517,9 @@ 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),
+    require('./series').exportFollows(userId, db),
+    require('./seasonPass').exportPurchases(userId, db),
   ]);
 
   return {
@@ -549,6 +562,9 @@ 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,
+    seriesFollowed,
+    seasonPasses,
   };
 }
 
@@ -605,6 +621,18 @@ 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.seasonPasses?.length) {
+    heading('Season passes');
+    for (const s of data.seasonPasses) para(`${fmt(s.at)} — ${s.quantity} × ${s.pass}, R${Number(s.total).toFixed(2)} (${s.status})`);
+  }
+  if (data.seriesFollowed?.length) {
+    heading('Event series you follow');
+    for (const f of data.seriesFollowed) para(`${f.series} — since ${fmt(f.since)}`);
+  }
   if (data.feedback.length) {
     heading('Feedback you gave');
     for (const f of data.feedback) {

backend/src/utils/privacyNotice.js

@@ -24,11 +24,12 @@ const DEFAULT_SECTIONS = [
     title: 'Plain English Summary',
     body: [
       "We respect your privacy — here's what you need to know:",
-      '• We only collect info needed to run events: registrations, payments, tickets and check-in.',
-      '• We store your info safely on South African servers.',
-      "• We don't sell your data, and only share it with the services listed in section 9, which process payments and deliver messages for us.",
+      '• We only collect info needed to run events: registrations, payments, tickets, check-in, volunteer rosters and, for children\'s ministry, kids check-in.',
+      "• Your information is kept in this site's own database, run by the hosting provider listed in section 9. It isn't shared with other organisations that use the same software.",
+      "• We don't sell your data, and only share it with the services listed in section 9 — they process payments and deliver messages for us, and any other system we connect (such as church-management software) gets only the updates we chose.",
       '• If you register other people or pass a ticket on, we only use the email or phone number you type to contact them. We never show you whether someone has an account with us.',
       '• For youth events, a parent or guardian gives consent. Medical details are encrypted, seen only by the event leaders who need them, and deleted shortly after the event.',
+      "• For kids check-in, parents add their children's details once. Allergies, medical and custody notes are encrypted, shown only to kids-ministry staff, and deleted when a child hasn't been checked in for a while (section 7). Children are collected with a pickup code.",
       '• Online payments go through Yoco or PayFast; we never see your card details.',
       '• We send tickets, updates and security alerts by email and/or WhatsApp. News and announcements are sent only if you ask for them, and you can unsubscribe at any time.',
       '• Visit statistics are only collected if you click "Allow" on the cookie notice — no third-party analytics.',
@@ -50,8 +51,12 @@ const DEFAULT_SECTIONS = [
       'We collect the following information when you interact with our platform:',
       '• Account information: name, email address, phone number, notification preference and password (stored only as an encrypted hash). If you use two-factor authentication, we keep which method you use; codes are short-lived and never stored in readable form.',
       '• Security records: sign-ins, password changes and similar account events, with the time, IP address and device type, so we can alert you and investigate misuse.',
-      '• Event information: events you register for, ticket selections, discount codes used, attendee form answers, waitlist requests, ticket check-ins (when your ticket was scanned), and room or group allocations.',
-      '• Details about other people you register (see section 3), and parental consent details for youth events (see section 8).',
+      '• Event information: events you register for, ticket selections (including the sessions you chose on multi-session events), discount codes used, attendee form answers, waitlist requests, ticket check-ins (when your ticket was scanned, per session), room or group allocations, and completion certificates issued to you.',
+      '• Your home campus, if the organisation has more than one campus and you choose one.',
+      '• Serving (if you volunteer): the roles and shifts you sign up for or are given, requests to pass a shift on and who took it, when you checked in, and the hours you served.',
+      '• Event series you follow, and season passes you buy (a season pass registers you for each event on it, so each shows in your registrations).',
+      "• Kids check-in (if you use it): your family's name, your children's names, dates of birth, gender, allergies, medical notes and custody notes, the adults you allow to collect them (name, phone number, relationship), and each check-in — when, which room, the pickup code, who checked them in and out, and who collected them (see section 8).",
+      '• Details about other people you register (see section 3), parental consent details for youth events, and children at kids check-in (see section 8).',
       '• Payment information: processed by our payment provider (Yoco or PayFast); we receive only payment status, amount and reference numbers. If you sponsor a spot, we record the amount and, unless you give anonymously, the name and message you choose to add.',
       "• Feedback: answers you give to post-event feedback forms. If an event's feedback is anonymous, your answers are not linked to your name.",
       '• Your choices: whether you want news and announcements, which version of this notice you accepted, and when you made each choice.',
@@ -83,7 +88,12 @@ const DEFAULT_SECTIONS = [
       '• Send news and announcements about upcoming events, only if you asked for them. Every such email has an unsubscribe link, and you can reply STOP on WhatsApp.',
       '• Send security notifications for new logins, password changes, and account actions on your account.',
       '• Deliver your event tickets via email attachment and/or WhatsApp PDF (based on your preference).',
-      '• Check tickets in at the door, including with scanners that keep working without an internet connection.',
+      '• Check tickets in at the door, including with scanners that keep working without an internet connection, and keep attendance per session on multi-session events.',
+      '• Send optional reminders before sessions, and issue completion certificates (each has a code anyone can use to check it is genuine: the check shows the name on the certificate and the event).',
+      '• Check children in and out at kids check-in, send you their pickup code, and ask you to come to the room if a leader needs you.',
+      '• Show you the events of your home campus first, if the organisation has more than one campus.',
+      '• Run volunteer rosters: remind you the day before you serve, pass your shift on to someone who accepts it when you can\'t make it, and check you in when you arrive.',
+      '• Tell you when a new event in a series you follow comes out. This counts as news, so it\'s only sent if you get news and announcements.',
       '• Offer places from a waitlist, arrange rooms and groups, and ask for parental consent on youth events.',
       '• Send you an optional feedback form after an event, with one reminder.',
       '• Manage user accounts and event attendance records, and give support when you ask for help.',
@@ -99,7 +109,9 @@ const DEFAULT_SECTIONS = [
       '• Event registration confirmations and updates.',
       '• Payment receipts.',
       '• Your event tickets (as a PDF document).',
-      '• Security alerts such as new login notifications, password changes, and account closure confirmations.',
+      '• Security alerts such as new login notifications, password changes, and account closure confirmations, and sign-in codes if you chose WhatsApp for two-factor authentication.',
+      '• Session reminders, if the event sends them, and volunteer reminders the day before you serve.',
+      '• Kids check-in: your children\'s pickup code, and a request to come to the room if a leader needs you. These never include medical or custody details. If you ask the desk to, the pickup code is also sent to one of your authorised adults.',
       '• News and announcements, only if you asked for them on WhatsApp. Reply STOP to any of these to stop them.',
       'WhatsApp communications are delivered through WAWP (wawp.net), a third-party WhatsApp Business API provider. Your mobile number is transmitted to WAWP solely for the purpose of delivering your messages.',
       'Security-critical messages (login alerts, password resets, account closures) are always sent via email regardless of your preference, and additionally sent via WhatsApp if your preference includes it.',
@@ -113,7 +125,8 @@ const DEFAULT_SECTIONS = [
     id: 'storage',
     title: '6. Where We Store Your Data',
     body: [
-      'All data is securely stored on cloud servers hosted in South Africa.',
+      "Your information is stored in this site's own database, on the servers of the hosting provider listed in section 9 (where they are is shown there). Each organisation using this software has its own separate site and database.",
+      'The software (Cross Events) is licensed from Cross Code. Every 15 minutes the site sends Cross Code\'s licence server technical health information (software version, uptime, disk space, errors) and totals — such as the number of accounts, events, registrations, tickets and check-ins, and income as a broad range (for example "R5 001–R20 000"). It never sends names, contact details, children\'s details or any other personal information.',
       'We use appropriate technical and organisational measures to protect your information from unauthorised access, alteration, or disclosure.',
     ].join('\n'),
   },
@@ -124,18 +137,26 @@ const DEFAULT_SECTIONS = [
       'We keep personal information only as long as we need it:',
       '{retention}',
       "• Ticket lists downloaded to a staff member's scanner for offline check-in are deleted from that device when offline mode is ended.",
+      '• Copies of the updates sent to connected systems (webhooks, section 9) are kept for 30 days so problems can be checked, then deleted — and straight away when your account is deleted.',
+      "• Family lists downloaded to a kids check-in desk for offline use stay on that device until the desk is synced and the list is refreshed or removed. Only kids-ministry staff can download them, and each download is recorded.",
       'You can ask for your account to be deleted at any time from the Privacy page in your account. Your account is closed straight away, and your personal information — your name and contact details, the people you registered, your form answers — is deleted within 30 days (after any upcoming event you registered for). Payment and registration records are kept without your name, because the law requires us to keep financial records.',
     ].join('\n'),
   },
   {
     id: 'children',
-    title: '8. Children, Parental Consent and Health Information',
+    title: '8. Children, Parental Consent, Kids Check-in and Health Information',
     body: [
       'Users under 18 may only create an account or register for events with the consent and supervision of a parent or guardian.',
       'We do not knowingly collect or process personal information of minors without such consent.',
       "For youth events, each attendee's date of birth is required. For anyone under 18, the parent or guardian named at registration is sent a consent request by email and WhatsApp, where they review the event details and give or decline consent. Their typed name, the time, the wording agreed to, and the IP address and device type used are recorded as proof of consent. A young person can't be checked in until consent is given.",
       "The consent form may ask for medical information (such as allergies, medication and conditions) and an emergency contact. This is special personal information under POPIA. We collect it only with the parent's or guardian's consent, for the young person's safety at the event. It is stored encrypted and shown only to supervisors who need it, and each time the medical list is viewed this is recorded. It is deleted after the event as described in section 7.",
       'A parent or guardian may also say whether photos of the young person may be used.',
+      'Kids check-in:',
+      "• A parent adds their children under My account → Kids, or the kids desk adds them with the parent present. A parent who is added at the desk with only a phone number or email address gets an account they can activate.",
+      "• Allergies, medical notes and custody notes (for example, someone who may not collect a child) are special personal information. We keep them only to keep your child safe, with your consent as their parent or guardian. They are stored encrypted, shown only to kids-ministry staff at the desk and in the rooms, and never put in a message. Opening the desk or room screens is recorded. Only parents, supervisors and administrators can change custody notes, and every change is recorded.",
+      '• Each check-in gives you a pickup code. Anyone who has the code can collect your children, so share it only with people you trust. The adults you list as allowed to collect are shown to the room leader so they can check.',
+      '• Each child is added to the event\'s attendance records (name, date of birth and gender) like any other attendee, so the organisation knows who attended.',
+      "• A child's details are deleted when they haven't been checked in for the period in section 7. You can remove them yourself at any time.",
     ].join('\n'),
   },
   {
@@ -145,9 +166,13 @@ const DEFAULT_SECTIONS = [
       'We do not sell or rent your personal information. Outside our organisation, it is shared only with these service providers ("operators"), each only for its purpose:',
       '{operators}',
       '• Anyone we are required to share it with under South African law.',
+      'If we connect another system — for example our church-management software — through a webhook, it is listed above with what it receives. It gets only the updates we chose (such as new registrations, payments and check-ins), and never children\'s details from kids check-in.',
       'Within our organisation, people see only what they need:',
       "• Door staff see a ticket's holder name, ticket type and check-in status when scanning.",
-      '• Group, room or bus leaders see the names, ages and contact numbers of the people in their group. Medical details are shown to supervisors only.',
+      '• Group, room or bus leaders see the names, ages and contact numbers of the people in their group. Medical details from parental consent forms are shown to supervisors only.',
+      "• Kids-ministry staff see the children checked in, with their allergies, medical and custody notes, the parents' names and phone numbers, and the adults allowed to collect them.",
+      '• Staff running a volunteer roster see who is serving in each role, their contact details, check-ins and hours. If you ask for someone to take over your shift, your first name, the role and any note you add are shown to the event\x27s other volunteers and others who could take it over.',
+      '• If the organisation has several campuses, a staff member may be limited to their own campuses\' events.',
       '• Supervisors and administrators manage registrations, payments and communication for events. Every export of personal information (reports, attendance registers, lists) is recorded.',
       '• Support access: to help with a problem (for example, a ticket not showing), an administrator may view the site as you see it for up to 30 minutes. This is strictly read-only — nothing can be changed, paid, registered or sent on your behalf. A reason must be given, and the session and every page viewed are recorded. The organisation may choose to email you whenever this happens.',
       '• Sponsors never see who was helped by a sponsorship; the public only sees how many spots were sponsored.',
@@ -186,6 +211,9 @@ const DEFAULT_SECTIONS = [
       'Staff and administrators only:',
       '• hope_events_scan_device, hope_events_offline_lock and the "hope-events-offline-scan" database — on a staff member\'s scanner in offline mode: the device\'s id, the ticket list for the section being scanned, and scans waiting to upload. They are deleted when offline mode is ended. A copy of the scanner page is also cached so it opens without a connection.',
       '• hope_events_admin_token, hope_events_admin_user_cache and hope_events_impersonation — only while an administrator is using read-only support access (section 9), and removed when it ends.',
+      "• hope_events_kids_event and hope_events_kids_room — on a kids check-in device: the event and room last chosen.",
+      '• cross_events_dismissed_notices — notices from the software provider (such as planned maintenance) that you have closed.',
+      "• hope_events_kids_device and hope_events_kids_offline_… — on a kids check-in desk in offline mode: the device's id, the list of families and children (with allergies, medical and custody notes), pickup codes kept for the device, and check-ins waiting to sync.",
       'Optional — only if you click "Allow" on the cookie notice:',
       '• hope_events_analytics_sid — a random, anonymous visit id. With it we count, in our own statistics, how many visitors view an event, start registering, and complete a registration. We record only that step, where the visit came from (for example a short link or campaign link) and the type of device — never your name, IP address or browsing history. Detailed records become anonymous daily totals after 90 days. If you choose "No thanks", nothing is counted and no visit id is created.',
       'Third parties:',
@@ -198,7 +226,7 @@ const DEFAULT_SECTIONS = [
     id: 'security',
     title: '12. Security',
     body: [
-      'Your personal data is encrypted during transmission and stored using industry-standard security protocols. Medical and emergency details are additionally encrypted in our database.',
+      "Your personal data is encrypted during transmission and stored using industry-standard security protocols. Medical and emergency details, and children's allergies, medical and custody notes, are additionally encrypted in our database.",
       'Passwords are encrypted and cannot be viewed by anyone, including administrators.',
       'Two-factor authentication is available to everyone and is required for supervisors and administrators.',
       'Links we send for consent, feedback, ticket transfers and unsubscribing are personal. Only a secure fingerprint of most links is stored, not the link itself.',
@@ -210,6 +238,7 @@ const DEFAULT_SECTIONS = [
     title: '13. Changes to This Notice',
     body: [
       'We may update this notice from time to time. Each update is published as a new version with its date, and earlier versions stay available on this page.',
+      'You are asked to agree to this notice when you create an account, or when you activate an account that was made for you (for example when someone registered you, or at the door). If you have never agreed to it — such as an account from before we asked — we ask once, the next time you log in.',
       'If a change is significant, we ask you to accept the new version the next time you log in.',
     ].join('\n'),
   },
@@ -233,6 +262,49 @@ const DEFAULT_SECTIONS = [
   },
 ];
 
+/**
+ * Changes to the built-in text, newest last. A site that published its own version keeps its own
+ * text, so the editor lists the changes made since the revision it last reviewed
+ * (`privacy_notice_builtin_reviewed`) and offers the new text section by section.
+ */
+const BUILT_IN_UPDATES = [
+  {
+    revision: '1.48.1',
+    summary: [
+      'Volunteer rosters: what is kept about people who serve, reminders, and who sees the roster.',
+      'Following an event series, and season passes.',
+      'Webhooks: other systems the organisation connects, what they receive, and that copies are kept 30 days.',
+      'How people agree to the notice: at sign-up, at account activation, or once after login if they never have.',
+      'A browser-storage item for closed provider notices.',
+    ],
+    sections: ['summary', 'information', 'use', 'whatsapp', 'retention', 'sharing', 'cookies', 'changes'],
+  },
+];
+const BUILT_IN_REVISION = BUILT_IN_UPDATES[BUILT_IN_UPDATES.length - 1].revision;
+const REVIEWED_KEY = 'privacy_notice_builtin_reviewed';
+
+function revisionLess(a, b) {
+  const pa = String(a || '0').split('.').map(Number);
+  const pb = String(b || '0').split('.').map(Number);
+  for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) < (pb[i] || 0);
+  return false;
+}
+
+/**
+ * Built-in text changes this site hasn't reviewed yet. None while nothing is published (the site
+ * shows the built-in text, so it is always current).
+ */
+async function builtInUpdates(db = prisma) {
+  if (!(await latestNotice(db))) return [];
+  const row = await db.appSetting.findUnique({ where: { key: REVIEWED_KEY } });
+  return BUILT_IN_UPDATES.filter(u => !row?.value || revisionLess(row.value, u.revision));
+}
+
+/** The admin has gone through the built-in changes (taken what they want, or not). */
+async function markBuiltInReviewed(db = prisma) {
+  await db.appSetting.upsert({ where: { key: REVIEWED_KEY }, update: { value: BUILT_IN_REVISION }, create: { key: REVIEWED_KEY, value: BUILT_IN_REVISION } });
+}
+
 function defaultSections() {
   return DEFAULT_SECTIONS.map(s => ({ ...s }));
 }
@@ -320,11 +392,17 @@ async function requiredVersion(db = prisma) {
   return row ? row.version : null;
 }
 
-/** Whether someone must (re-)accept the notice before carrying on. */
+/**
+ * Whether someone must accept the notice before carrying on, and why: 'first' — they never
+ * accepted any version (an account made for them by staff, at the door or by someone who
+ * registered them, or from before acceptances were recorded); 'updated' — a version marked as a
+ * significant change came out after the one they accepted. false when nothing is needed.
+ */
 async function noticePromptPending(user, db = prisma) {
+  if (user.noticeVersionAccepted == null) return 'first';
   const required = await requiredVersion(db);
   if (required == null) return false;
-  return (user.noticeVersionAccepted ?? -1) < required;
+  return user.noticeVersionAccepted < required ? 'updated' : false;
 }
 
 /**
@@ -427,6 +505,11 @@ async function publish({ sections, changeSummary, requiresAcceptance, publishedB
 
 module.exports = {
   PLACEHOLDERS,
+  BUILT_IN_UPDATES,
+  BUILT_IN_REVISION,
+  builtInUpdates,
+  markBuiltInReviewed,
+  revisionLess,
   defaultSections,
   cleanSections,
   noticeContext,

backend/src/utils/savedFilters.js

@@ -0,0 +1,100 @@
+/**
+ * Saved filters (1.49.2): a person names the filters they use on a list page and applies them
+ * with one click; one per page can be their default (applied when the page opens). Stored per
+ * person on the server, so they follow them to any device. Only their own are ever read or changed.
+ */
+
+const prisma = require('../config/db');
+
+// The list pages that have saved filters, and who can open them.
+const PAGES = { registrations: 'admin', users: 'admin', events: 'supervisor', reports: 'supervisor' };
+const MAX_PER_PAGE = 30;
+const MAX_PARAMS_BYTES = 4000;
+
+function filterError(message, statusCode = 400) {
+  const err = new Error(message);
+  err.statusCode = statusCode;
+  return err;
+}
+
+function cleanPage(page) {
+  const p = String(page || '');
+  if (!PAGES[p]) throw filterError('Unknown list page');
+  return p;
+}
+
+function cleanName(name) {
+  const n = String(name || '').trim().replace(/\s+/g, ' ');
+  if (!n) throw filterError('Give the filter a name');
+  return n.slice(0, 60);
+}
+
+/** The filter values: a plain object of strings, numbers, booleans and lists of strings. Pure. */
+function cleanParams(params) {
+  if (!params || typeof params !== 'object' || Array.isArray(params)) throw filterError('Nothing to save');
+  const out = {};
+  for (const [k, v] of Object.entries(params)) {
+    if (!/^[a-zA-Z][a-zA-Z0-9_]{0,39}$/.test(k)) continue;
+    if (typeof v === 'string') out[k] = v.slice(0, 500);
+    else if (typeof v === 'number' && Number.isFinite(v)) out[k] = v;
+    else if (typeof v === 'boolean') out[k] = v;
+    else if (Array.isArray(v)) out[k] = v.filter(x => typeof x === 'string').slice(0, 200).map(x => x.slice(0, 100));
+  }
+  if (JSON.stringify(out).length > MAX_PARAMS_BYTES) throw filterError('Too much to save in one filter');
+  return out;
+}
+
+const view = f => ({ id: f.id, page: f.page, name: f.name, params: f.params, isDefault: f.isDefault, updatedAt: f.updatedAt });
+
+async function list(userId, page) {
+  const rows = await prisma.savedFilter.findMany({ where: { userId, page: cleanPage(page) }, orderBy: [{ isDefault: 'desc' }, { name: 'asc' }] });
+  return rows.map(view);
+}
+
+/** Saves (or replaces, by name) a filter. Making it the default clears the old default. */
+async function save(userId, { page, name, params, isDefault = false }) {
+  const p = cleanPage(page);
+  const n = cleanName(name);
+  const data = cleanParams(params);
+  const existing = await prisma.savedFilter.findUnique({ where: { userId_page_name: { userId, page: p, name: n } } });
+  if (!existing && (await prisma.savedFilter.count({ where: { userId, page: p } })) >= MAX_PER_PAGE) {
+    throw filterError(`You can keep up to ${MAX_PER_PAGE} filters on a page — delete one first`);
+  }
+  return prisma.$transaction(async tx => {
+    if (isDefault) await tx.savedFilter.updateMany({ where: { userId, page: p, isDefault: true }, data: { isDefault: false } });
+    const row = existing
+      ? await tx.savedFilter.update({ where: { id: existing.id }, data: { params: data, ...(isDefault ? { isDefault: true } : {}) } })
+      : await tx.savedFilter.create({ data: { userId, page: p, name: n, params: data, isDefault: !!isDefault } });
+    return view(row);
+  });
+}
+
+async function own(userId, id) {
+  const row = await prisma.savedFilter.findUnique({ where: { id: String(id) } });
+  if (!row || row.userId !== userId) throw filterError('Saved filter not found', 404);
+  return row;
+}
+
+/** Rename, or make (or stop being) the default. */
+async function update(userId, id, { name, isDefault }) {
+  const row = await own(userId, id);
+  return prisma.$transaction(async tx => {
+    if (isDefault === true) await tx.savedFilter.updateMany({ where: { userId, page: row.page, isDefault: true, NOT: { id: row.id } }, data: { isDefault: false } });
+    try {
+      return view(await tx.savedFilter.update({
+        where: { id: row.id },
+        data: { ...(name !== undefined ? { name: cleanName(name) } : {}), ...(isDefault !== undefined ? { isDefault: isDefault === true } : {}) },
+      }));
+    } catch (e) {
+      if (e?.code === 'P2002') throw filterError('You already have a filter with that name on this page');
+      throw e;
+    }
+  });
+}
+
+async function remove(userId, id) {
+  const row = await own(userId, id);
+  await prisma.savedFilter.delete({ where: { id: row.id } });
+}
+
+module.exports = { PAGES, MAX_PER_PAGE, cleanParams, cleanName, cleanPage, list, save, update, remove };

backend/src/utils/seasonPass.js

@@ -0,0 +1,361 @@
+/**
+ * Season passes (1.47.3): one price for a ticket at each of several events in a series.
+ *
+ * - A supervisor picks the events on the pass, and which ticket (and variant) at each.
+ * - Buying registers the buyer at every event on it at once (`quantity` places each) and starts
+ *   one online checkout for the total. A free pass gives the tickets straight away.
+ * - The price is split across the events in proportion to their normal ticket prices (whole
+ *   cents, `splitCents`), and each registration's line is priced at its event's share, so every
+ *   event's cashup and reports count only its part. Those lines are never repriced, take no
+ *   coupons, and can't be edited.
+ * - The payment comes back as one provider payment; it's recorded as one Payment per event
+ *   (`recordPassPayment`), all linked to the purchase.
+ * - A pass stops selling when the first event on it starts, at its sale end, or when switched off.
+ */
+
+const prisma = require('../config/db');
+const { v4: uuidv4 } = require('uuid');
+
+function passError(message, statusCode = 400) {
+  const err = new Error(message);
+  err.statusCode = statusCode;
+  return err;
+}
+
+const toCents = n => Math.round(Number(n || 0) * 100);
+
+/**
+ * Splits `totalCents` in proportion to `weights` (whole cents that add up exactly; the cents
+ * left over by rounding down go to the largest remainders). All weights zero → equal parts.
+ * Pure, for tests.
+ */
+function splitCents(totalCents, weights) {
+  if (!weights.length) return [];
+  const w = weights.map(x => Math.max(0, Number(x) || 0));
+  const sum = w.reduce((s, x) => s + x, 0);
+  const shares = sum > 0 ? w.map(x => (totalCents * x) / sum) : w.map(() => totalCents / w.length);
+  const out = shares.map(Math.floor);
+  let left = totalCents - out.reduce((s, x) => s + x, 0);
+  const order = shares.map((s, i) => ({ i, frac: s - Math.floor(s) })).sort((a, b) => b.frac - a.frac || a.i - b.i);
+  for (let k = 0; left > 0; k = (k + 1) % order.length, left--) out[order[k].i]++;
+  return out;
+}
+
+/** The normal price of one place on an item: the variant's own price, else the option's. */
+function normalPrice(item) {
+  const v = item.variant;
+  return Number(v && v.price !== null && v.price !== undefined ? v.price : item.eventOption?.price || 0);
+}
+
+/**
+ * Each item's share of the pass price (rand, one pass), in proportion to its normal price.
+ * Pure, for tests: items need eventOption.price (and variant.price when there is one).
+ */
+function itemShares(price, items) {
+  return splitCents(toCents(price), items.map(i => toCents(normalPrice(i)))).map(c => c / 100);
+}
+
+/**
+ * How much of a payment goes to each registration: each gets what it still owes, in order, and
+ * anything over goes to the last one. `dues` in rand. Pure, for tests.
+ */
+function allocate(dues, amount) {
+  let left = toCents(amount);
+  const out = dues.map(d => {
+    const take = Math.min(left, Math.max(0, toCents(d)));
+    left -= take;
+    return take;
+  });
+  if (left > 0 && out.length) out[out.length - 1] += left;
+  return out.map(c => c / 100);
+}
+
+const ITEM_INCLUDE = {
+  event: {
+    select: {
+      id: true, title: true, startDate: true, endDate: true, isActive: true, seriesId: true, campusId: true,
+      registrationDeadline: true, scheduleType: true, attendanceMode: true, lateJoinEnabled: true, lateJoinUntilSessionId: true,
+      requiresParentalConsent: true, requiresRegistration: true, cashupStatus: true, kidsOptionId: true, volunteerOptionId: true,
+      sessions: { select: { id: true, startsAt: true, endsAt: true, cancelledAt: true } },
+    },
+  },
+  eventOption: { select: { id: true, name: true, price: true, stockLimit: true, eventId: true, sessionMode: true } },
+  variant: { select: { id: true, name: true, price: true, stockLimit: true, eventOptionId: true } },
+};
+const PASS_INCLUDE = { items: { orderBy: { order: 'asc' }, include: ITEM_INCLUDE }, series: { select: { id: true, name: true, slug: true } } };
+
+/** Why a pass can't be bought right now, or null. */
+function notOnSale(pass, now = new Date()) {
+  if (!pass.isActive) return 'This pass isn\'t on sale.';
+  if (!pass.items.length) return 'This pass has no events yet.';
+  if (pass.saleEndsAt && new Date(pass.saleEndsAt) <= now) return 'This pass is no longer on sale.';
+  const { wholeCourseClosesAt } = require('./sessions');
+  for (const i of pass.items) {
+    if (!i.event.isActive || i.event.cashupStatus === 'closed') return `${i.event.title} isn't taking registrations.`;
+    if (new Date(i.event.startDate) <= now) return 'This pass stopped selling when its first event started.';
+    if (wholeCourseClosesAt(i.event, i.event.sessions) <= now) return `Registration for ${i.event.title} has closed.`;
+  }
+  return null;
+}
+
+/** A pass as shown to buyers and supervisors: its events with normal prices and shares. */
+function passView(pass, now = new Date()) {
+  const shares = itemShares(pass.price, pass.items);
+  const normalValue = Math.round(pass.items.reduce((s, i) => s + normalPrice(i), 0) * 100) / 100;
+  return {
+    id: pass.id, seriesId: pass.seriesId, name: pass.name, description: pass.description, price: pass.price,
+    isActive: pass.isActive, saleEndsAt: pass.saleEndsAt, series: pass.series,
+    normalValue, saving: Math.max(0, Math.round((normalValue - pass.price) * 100) / 100),
+    unavailable: notOnSale(pass, now),
+    items: pass.items.map((i, k) => ({
+      id: i.id, eventId: i.eventId, eventOptionId: i.eventOptionId, variantId: i.variantId,
+      eventTitle: i.event.title, startDate: i.event.startDate, endDate: i.event.endDate, campusId: i.event.campusId,
+      ticket: i.variant ? `${i.eventOption.name} — ${i.variant.name}` : i.eventOption.name,
+      normalPrice: normalPrice(i), share: shares[k],
+    })),
+  };
+}
+
+// ─── Setting passes up ───────────────────────────────────────────────────────
+
+/**
+ * Checks a create/update body against the series' events: each item is an event in the series
+ * with one of its tickets (not the staff-only kids/volunteer ones, not a per-session ticket) and
+ * no parental consent (a pass can't collect children's details). Returns the data to save and the
+ * events on it (for the campus check).
+ */
+async function cleanPassInput(body, seriesId, current = null, db = prisma) {
+  const data = {};
+  if (body.name !== undefined || !current) {
+    const name = String(body.name || '').trim();
+    if (!name) throw passError('Give the pass a name');
+    data.name = name.slice(0, 120);
+  }
+  if (body.description !== undefined) data.description = String(body.description || '').trim() || null;
+  if (body.price !== undefined || !current) {
+    const price = Number(body.price);
+    if (!(price >= 0) || !Number.isFinite(price)) throw passError('Enter the pass price (0 for free)');
+    data.price = Math.round(price * 100) / 100;
+  }
+  if (body.isActive !== undefined) data.isActive = body.isActive !== false;
+  if (body.saleEndsAt !== undefined) {
+    const d = body.saleEndsAt ? new Date(body.saleEndsAt) : null;
+    if (d && isNaN(d.getTime())) throw passError('The sale end date isn\'t valid');
+    data.saleEndsAt = d;
+  }
+
+  let items = null;
+  if (body.items !== undefined || !current) {
+    if (!Array.isArray(body.items) || body.items.length === 0) throw passError('Choose at least one event for the pass');
+    const seen = new Set();
+    items = [];
+    for (const [order, raw] of body.items.entries()) {
+      const eventId = String(raw?.eventId || '');
+      if (seen.has(eventId)) throw passError('Each event can only be on a pass once');
+      seen.add(eventId);
+      const event = await db.event.findUnique({
+        where: { id: eventId },
+        select: { id: true, title: true, seriesId: true, campusId: true, requiresParentalConsent: true, requiresRegistration: true, kidsOptionId: true, volunteerOptionId: true, scheduleType: true, attendanceMode: true, eventOptions: { select: { id: true, sessionMode: true, variants: { select: { id: true } } } } },
+      });
+      if (!event || event.seriesId !== seriesId) throw passError('Every event on a pass must be in its series');
+      if (event.requiresParentalConsent) throw passError(`${event.title} is a youth event (parental consent), so it can't be on a pass`);
+      if (event.requiresRegistration === false) throw passError(`${event.title} doesn't take registrations`);
+      const option = event.eventOptions.find(o => o.id === raw.eventOptionId);
+      if (!option || [event.kidsOptionId, event.volunteerOptionId].includes(option.id)) throw passError(`Choose a ticket for ${event.title}`);
+      if (event.scheduleType === 'sessions' && event.attendanceMode === 'pick' && option.sessionMode === 'pick') {
+        throw passError(`${event.title}: choose a ticket for all sessions, not a per-session one`);
+      }
+      const variantId = raw.variantId ? String(raw.variantId) : null;
+      if (variantId && !option.variants.some(v => v.id === variantId)) throw passError(`That variant isn't one of the ticket's at ${event.title}`);
+      items.push({ eventId, eventOptionId: option.id, variantId, order, campusId: event.campusId });
+    }
+  }
+  return { data, items };
+}
+
+async function loadPass(id, db = prisma) {
+  const pass = await db.seasonPass.findUnique({ where: { id }, include: PASS_INCLUDE });
+  if (!pass) throw passError('Season pass not found', 404);
+  return pass;
+}
+
+// ─── Buying ──────────────────────────────────────────────────────────────────
+
+/**
+ * Buys `quantity` passes for `userId`: a registration at each event (lines priced at the share),
+ * then one checkout for the total — or, for a free pass, the tickets straight away.
+ * @returns {Promise<{ purchaseId, total, paid, redirectUrl, provider, message }>}
+ */
+async function buyPass(passId, userId, { quantity = 1, provider = null, successUrl, cancelUrl, failureUrl } = {}) {
+  const qty = parseInt(quantity, 10);
+  if (!(qty >= 1 && qty <= 20)) throw passError('Choose how many passes (1 to 20)');
+  const pass = await loadPass(passId);
+  const reason = notOnSale(pass);
+  if (reason) throw passError(reason, 409);
+  const shares = itemShares(pass.price, pass.items);
+  const total = Math.round(pass.price * qty * 100) / 100;
+  const free = total === 0;
+
+  const { remainingFor } = require('./stock');
+  const purchase = await prisma.$transaction(async tx => {
+    // One buyer at a time per pass, so the last places can't be sold twice through passes.
+    await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtext(${'seasonpass:' + pass.id}))`;
+    for (const i of pass.items) {
+      const left = await remainingFor(i.eventOption, i.variant, { db: tx });
+      if (left !== null && left < qty) throw passError(`${i.event.title} has ${left === 0 ? 'no places' : `only ${left} place${left === 1 ? '' : 's'}`} left for ${i.variant ? i.variant.name : i.eventOption.name}`, 409);
+    }
+    const created = await tx.seasonPassPurchase.create({ data: { passId: pass.id, userId, quantity: qty, total, status: free ? 'paid' : 'pending' } });
+    for (const [k, i] of pass.items.entries()) {
+      const registration = await tx.registration.create({
+        data: { userId, eventId: i.eventId, status: free ? 'paid' : 'pending', seasonPassPurchaseId: created.id },
+      });
+      const line = await tx.registrationOption.create({
+        data: { registrationId: registration.id, eventOptionId: i.eventOptionId, variantId: i.variantId, quantity: qty, priceSnapshot: shares[k] },
+      });
+      await tx.registrationOptionTranche.create({ data: { registrationOptionId: line.id, quantity: qty, priceSnapshot: shares[k] } });
+    }
+    return created;
+  });
+
+  const registrations = await prisma.registration.findMany({ where: { seasonPassPurchaseId: purchase.id }, select: { id: true } });
+  if (free) {
+    const { generateTicketsForRegistration } = require('./ticketUtils');
+    for (const r of registrations) await generateTicketsForRegistration(r.id).catch(e => console.error('[season-pass] tickets:', e?.message || e));
+    emailTicketsFor(userId, registrations.map(r => r.id));
+    return { purchaseId: purchase.id, total, paid: true, redirectUrl: null, provider: null, message: 'Your tickets are ready.' };
+  }
+  return { purchaseId: purchase.id, total, paid: false, ...(await startPassCheckout(purchase.id, userId, { provider, successUrl, cancelUrl, failureUrl })) };
+}
+
+/**
+ * Starts (or restarts) the online checkout for what's still owed on a purchase. When online
+ * payment isn't possible (none set up, or under the minimum) the places stay booked unpaid and
+ * the buyer is told to pay the church.
+ */
+async function startPassCheckout(purchaseId, userId, { provider = null, successUrl, cancelUrl, failureUrl } = {}) {
+  const purchase = await prisma.seasonPassPurchase.findUnique({
+    where: { id: purchaseId },
+    include: {
+      pass: { select: { name: true } },
+      user: { select: { name: true, email: true } },
+      registrations: { include: { event: { select: { title: true } }, registrationOptions: { include: { tranches: true } }, payments: true } },
+    },
+  });
+  if (!purchase || purchase.userId !== userId) throw passError('Purchase not found', 404);
+  const { computeRegistrationTotalDue } = require('./pricing');
+  const owed = purchase.registrations
+    .filter(r => r.status !== 'cancelled')
+    .map(r => ({ r, due: Math.max(0, computeRegistrationTotalDue(r, new Date()) - r.payments.reduce((s, p) => s + p.amount, 0)) }))
+    .filter(x => x.due > 0.004);
+  const amountCents = owed.reduce((s, x) => s + toCents(x.due), 0);
+  if (amountCents <= 0) throw passError('This pass is already paid');
+
+  const payments = require('../payments');
+  try {
+    const checkout = await payments.createCheckout(provider, {
+      amountCents,
+      metadata: { type: 'season_pass', purchaseId: purchase.id, userId, passName: purchase.pass.name },
+      lineItems: owed.map(x => ({ name: `${purchase.pass.name}: ${x.r.event.title}`, quantity: 1, unitCents: toCents(x.due) })),
+      successUrl, cancelUrl, failureUrl,
+      payer: { name: purchase.user?.name || '', email: purchase.user?.email || '' },
+      description: purchase.pass.name,
+      idempotencyKey: `pass_${purchase.id}_${amountCents}_${Date.now()}`,
+    });
+    await prisma.seasonPassPurchase.update({ where: { id: purchase.id }, data: { checkoutId: checkout.checkoutId } });
+    return { redirectUrl: checkout.redirectUrl, provider: checkout.provider, message: null };
+  } catch (e) {
+    // Online payment not possible (switched off, not set up, or under the minimum): keep the places.
+    if (e.statusCode && (e.statusCode < 500 || e.statusCode === 503)) {
+      return { redirectUrl: null, provider: null, message: `Your places are booked. ${e.message}` };
+    }
+    throw e;
+  }
+}
+
+function emailTicketsFor(userId, registrationIds) {
+  (async () => {
+    const { emailTickets } = require('../controllers/ticketController');
+    for (const registrationId of registrationIds) {
+      const mockReq = { user: { id: userId }, body: { registrationId } };
+      const mockRes = { status: () => mockRes, json: () => {} };
+      try { await emailTickets(mockReq, mockRes); } catch (e) { console.error('[season-pass] emailing tickets:', e?.message || e); }
+    }
+  })();
+}
+
+/**
+ * A pass checkout was paid (webhook or status check): one Payment per registration on the
+ * purchase for what it owed, all linked to the purchase, then each registration's status and
+ * tickets. Idempotent on the provider's payment id (the first Payment carries it).
+ */
+async function recordPassPayment(providerId, event, body) {
+  const { externalId, amountCents, status, metadata = {}, methodType } = event.transaction;
+  const webhook = require('../payments/webhook');
+  const existing = await prisma.payment.findFirst({ where: { externalId } });
+  if (existing) {
+    await webhook.saveProviderTransaction(providerId, event, body, { reconciled: true, paymentId: existing.id }).catch(() => {});
+    return { status: 'already_processed', paymentId: existing.id, externalId };
+  }
+  const purchase = await prisma.seasonPassPurchase.findUnique({
+    where: { id: String(metadata.purchaseId || '') },
+    include: { registrations: { orderBy: { createdAt: 'asc' }, include: { registrationOptions: { include: { tranches: true } }, payments: true } } },
+  });
+  if (!purchase) throw passError(`Season pass purchase ${metadata.purchaseId} not found`, 404);
+
+  const { computeRegistrationTotalDue } = require('./pricing');
+  const regs = purchase.registrations.filter(r => r.status !== 'cancelled');
+  const dues = regs.map(r => Math.max(0, computeRegistrationTotalDue(r, new Date()) - r.payments.reduce((s, p) => s + p.amount, 0)));
+  const parts = allocate(dues, (amountCents || 0) / 100);
+  const method = methodType || 'card';
+  const paymentStatus = status === 'succeeded' ? 'completed' : status;
+
+  const created = [];
+  for (const [k, r] of regs.entries()) {
+    if (!(parts[k] > 0)) continue;
+    created.push(await prisma.payment.create({
+      data: {
+        id: uuidv4(), amount: parts[k], method, provider: providerId, status: paymentStatus,
+        externalId: created.length === 0 ? externalId : null,
+        registrationId: r.id, eventId: r.eventId, userId: purchase.userId, recordedById: purchase.userId,
+        seasonPassPurchaseId: purchase.id,
+      },
+    }));
+  }
+  const paidIds = [];
+  for (const r of regs) {
+    const updated = await webhook.updateRegistrationStatus(r.id);
+    if (updated.status === 'paid') paidIds.push(r.id);
+  }
+  if (paidIds.length === regs.length) await prisma.seasonPassPurchase.update({ where: { id: purchase.id }, data: { status: 'paid' } });
+  if (created[0]) await webhook.saveProviderTransaction(providerId, event, body, { reconciled: true, paymentId: created[0].id }).catch(() => {});
+
+  (async () => {
+    const { sendPaymentEmails } = require('./notifications');
+    for (const p of created) {
+      try { await sendPaymentEmails(p.id); } catch (e) { console.error('[season-pass] payment email:', e?.message || e); }
+    }
+  })();
+  emailTicketsFor(purchase.userId, paidIds);
+  return { status: 'success', purchaseId: purchase.id, payments: created.map(p => ({ id: p.id, amount: p.amount, eventId: p.eventId })) };
+}
+
+/** Route guard: a registration from a season pass keeps its lines as bought (no edits, no coupons). */
+function notOnSeasonPass(req, res, next) {
+  prisma.registration.findUnique({ where: { id: req.params.id }, select: { seasonPassPurchaseId: true } })
+    .then(r => (r?.seasonPassPurchaseId
+      ? res.status(409).json({ message: 'This registration is part of a season pass, so its tickets can\'t be changed and codes can\'t be added. Ask the organiser if something needs to change.' })
+      : next()))
+    .catch(next);
+}
+
+// ─── Privacy ─────────────────────────────────────────────────────────────────
+
+async function exportPurchases(userId, db = prisma) {
+  const rows = await db.seasonPassPurchase.findMany({ where: { userId }, orderBy: { createdAt: 'asc' }, select: { quantity: true, total: true, status: true, createdAt: true, pass: { select: { name: true } } } });
+  return rows.map(r => ({ pass: r.pass.name, quantity: r.quantity, total: r.total, status: r.status, at: r.createdAt }));
+}
+
+module.exports = {
+  splitCents, itemShares, allocate, normalPrice, notOnSale, passView, cleanPassInput, loadPass,
+  buyPass, startPassCheckout, recordPassPayment, notOnSeasonPass, exportPurchases, passError, PASS_INCLUDE,
+};

backend/src/utils/series.js

@@ -0,0 +1,240 @@
+/**
+ * Event series (1.47.1): separate events grouped on one series page — every year's camp, the
+ * monthly men's breakfast. A series isn't tied to a campus, so it can have events at several.
+ * Each event page links to the next public event in its series, and people can follow a series:
+ * when a new event in it goes live they get one email, sent as News & announcements (so only to
+ * people who opted in to news, with an unsubscribe link).
+ */
+
+const prisma = require('../config/db');
+const { slugify } = require('./campuses');
+
+function seriesError(message, statusCode = 400) {
+  const err = new Error(message);
+  err.statusCode = statusCode;
+  return err;
+}
+
+/** Events anyone can see: active, not hidden and live. */
+function publicEventWhere(now = new Date()) {
+  return { isActive: true, isHidden: false, goLiveAt: { lte: now } };
+}
+
+/** Name, slug, description and picture from a create/update body (`current` on update). */
+function cleanSeriesInput(body = {}, current = null) {
+  const data = {};
+  if (body.name !== undefined || !current) {
+    const name = String(body.name || '').trim();
+    if (!name) throw seriesError('Give the series a name');
+    if (name.length > 120) throw seriesError('The name is too long');
+    data.name = name;
+  }
+  if (body.slug !== undefined || !current) {
+    const slug = slugify(body.slug || data.name || current?.name);
+    if (!slug) throw seriesError('The web address needs letters or numbers');
+    data.slug = slug;
+  }
+  if (body.description !== undefined) data.description = String(body.description || '').trim() || null;
+  if (body.picture !== undefined) data.picture = String(body.picture || '').trim() || null;
+  return data;
+}
+
+/** The series to save on an event from a body's `seriesId`: undefined = leave as is, null = none. */
+async function seriesForEvent(seriesId, db = prisma) {
+  if (seriesId === undefined) return undefined;
+  if (!seriesId) return null;
+  const found = await db.eventSeries.findUnique({ where: { id: String(seriesId) }, select: { id: true } });
+  if (!found) throw seriesError('That series no longer exists');
+  return found.id;
+}
+
+const NEXT_SELECT = { id: true, title: true, startDate: true, endDate: true, location: true, redirectUrl: true };
+
+/**
+ * The next public event in the same series after `event` (starting later, not over yet), or null.
+ */
+async function nextInSeries(event, db = prisma, now = new Date()) {
+  if (!event?.seriesId) return null;
+  return db.event.findFirst({
+    where: { ...publicEventWhere(now), seriesId: event.seriesId, id: { not: event.id }, startDate: { gt: event.startDate }, endDate: { gte: now } },
+    orderBy: { startDate: 'asc' },
+    select: NEXT_SELECT,
+  });
+}
+
+/**
+ * Splits a series' public events into upcoming (not over yet, soonest first) and past (latest
+ * first). Pure, for the series page.
+ */
+function splitEvents(events, now = new Date()) {
+  const upcoming = events.filter(e => new Date(e.endDate) >= now).sort((a, b) => new Date(a.startDate) - new Date(b.startDate));
+  const past = events.filter(e => new Date(e.endDate) < now).sort((a, b) => new Date(b.startDate) - new Date(a.startDate));
+  return { upcoming, past };
+}
+
+// ─── Following ───────────────────────────────────────────────────────────────
+
+async function follow(seriesId, userId) {
+  const series = await prisma.eventSeries.findUnique({ where: { id: seriesId }, select: { id: true } });
+  if (!series) throw seriesError('Series not found', 404);
+  await prisma.seriesFollow.upsert({ where: { seriesId_userId: { seriesId, userId } }, create: { seriesId, userId }, update: {} });
+}
+
+async function unfollow(seriesId, userId) {
+  await prisma.seriesFollow.deleteMany({ where: { seriesId, userId } });
+}
+
+function frontendUrl() {
+  return String(process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');
+}
+
+/**
+ * The `series` job: for each event in a series that is now public and hasn't started, email the
+ * series' followers once. The event is claimed first (seriesAnnouncedAt), so a slow run or two
+ * workers never send twice. An event made public after it started is never announced.
+ */
+async function runAnnounceJob(now = new Date()) {
+  const due = await prisma.event.findMany({
+    where: { ...publicEventWhere(now), seriesId: { not: null }, seriesAnnouncedAt: null, startDate: { gt: now } },
+    select: { id: true, title: true, startDate: true, location: true, redirectUrl: true, series: { select: { id: true, name: true, slug: true } } },
+    take: 50,
+  });
+  let announced = 0;
+  let sent = 0;
+  let skipped = 0;
+  for (const ev of due) {
+    const claimed = await prisma.event.updateMany({ where: { id: ev.id, seriesAnnouncedAt: null }, data: { seriesAnnouncedAt: now } });
+    if (!claimed.count) continue;
+    announced++;
+    const follows = await prisma.seriesFollow.findMany({
+      where: { seriesId: ev.series.id, user: { isActive: true } },
+      select: { user: { select: { id: true, name: true, email: true } } },
+    });
+    const { filterRecipients, bulkEmailFooter } = require('./privacy');
+    const { recipients, skipped: notNews } = await filterRecipients(
+      follows.filter(f => f.user.email).map(f => ({ email: f.user.email, name: f.user.name, userId: f.user.id })),
+      { channel: 'email', kind: 'news' },
+    );
+    skipped += notNews;
+    const { sendMail } = require('./email');
+    for (const r of recipients) {
+      const footer = bulkEmailFooter({ kind: 'news', recipient: r });
+      const msg = announcementEmail({ name: r.name, event: ev, series: ev.series });
+      try {
+        await sendMail({ to: r.email, subject: msg.subject, html: msg.html + footer.html, text: msg.text + footer.text, headers: footer.headers });
+        sent++;
+      } catch (e) {
+        try { console.warn('[series] failed to email', r.email, e?.message || e); } catch {}
+      }
+    }
+  }
+  return { announced, sent, skipped };
+}
+
+function announcementEmail({ name, event, series }) {
+  const { emailWrapper, ctaButton } = require('./email');
+  const esc = s => String(s || '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  const when = new Date(event.startDate).toLocaleDateString('en-GB', { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' });
+  const url = `${frontendUrl()}/events/${event.id}`;
+  const seriesUrl = `${frontendUrl()}/series/${series.slug}`;
+  const subject = `New in ${series.name}: ${event.title}`;
+  const body = `
+    <p style="font-size:22px;font-weight:800;color:#0f172a;margin:0 0 8px 0;letter-spacing:-0.3px">${esc(event.title)}</p>
+    <p style="color:#64748b;font-size:14px;margin:0 0 24px 0">New in ${esc(series.name)}</p>
+    <p style="margin:0 0 16px 0;color:#374151">Hi <strong>${esc(name || 'there')}</strong>,</p>
+    <p style="margin:0 0 16px 0;color:#374151">You follow <strong>${esc(series.name)}</strong>, and the next one is out: <strong>${esc(event.title)}</strong> on ${esc(when)}${event.location ? `, ${esc(event.location)}` : ''}.</p>
+    ${ctaButton('See the event', url)}
+    <p style="margin:16px 0 0 0;font-size:13px;color:#64748b">To stop hearing about this series, unfollow it on <a href="${seriesUrl}" style="color:#64748b">its page</a>.</p>`;
+  const text = `Hi ${name || 'there'},\n\nYou follow ${series.name}, and the next one is out: ${event.title} on ${when}${event.location ? `, ${event.location}` : ''}.\n\nSee the event: ${url}\n\nTo stop hearing about this series, unfollow it on its page: ${seriesUrl}`;
+  return { subject, text, html: emailWrapper(body, { preheader: subject }) };
+}
+
+// ─── Year-on-year comparison (1.47.2) ────────────────────────────────────────
+
+// The same "real income" as the dashboard's top events: everything except the legs that apply an
+// earlier donation to an order (not new money). Refunds count, as negatives.
+const EXCLUDE_DONATION_LEGS = {
+  NOT: { AND: [{ isDonation: false }, { originalPaymentId: { not: null } }, { amount: { gt: 0 } }] },
+};
+
+const pct = (now, before) => (before > 0 ? Math.round(((now - before) / before) * 100) : null);
+
+/**
+ * Adds `change` to each row against the row before it (rows oldest first): the percentage up or
+ * down for registrations, tickets, income and checked in, null when there's nothing to compare.
+ * Pure, for tests.
+ */
+function withChanges(rows) {
+  return rows.map((r, i) => {
+    const prev = rows[i - 1];
+    return {
+      ...r,
+      change: prev
+        ? { registrations: pct(r.registrations, prev.registrations), tickets: pct(r.tickets, prev.tickets), income: pct(r.income, prev.income), checkedIn: pct(r.checkedIn, prev.checkedIn) }
+        : null,
+    };
+  });
+}
+
+/**
+ * Registrations, tickets, income and attendance for each event in a series that the person may
+ * see (`scopeWhere`, from campusScope.eventWhere), oldest first, with the change from the one
+ * before. Checked in: check-ins on a single-date event; on a multi-session event, the average per
+ * session that wasn't cancelled.
+ */
+async function compareSeries(seriesId, { scopeWhere = {} } = {}, db = prisma) {
+  const series = await db.eventSeries.findUnique({ where: { id: seriesId }, select: { id: true, name: true, slug: true } });
+  if (!series) throw seriesError('Series not found', 404);
+  const events = await db.event.findMany({
+    where: { AND: [{ seriesId }, scopeWhere] },
+    orderBy: { startDate: 'asc' },
+    select: {
+      id: true, title: true, startDate: true, endDate: true, scheduleType: true, isActive: true,
+      campus: { select: { id: true, name: true, slug: true, colour: true } },
+      _count: { select: { sessions: { where: { cancelledAt: null } } } },
+    },
+  });
+  const ids = events.map(e => e.id);
+  const [regs, tickets, income, usages] = ids.length ? await Promise.all([
+    db.registration.groupBy({ by: ['eventId'], where: { eventId: { in: ids }, status: { not: 'cancelled' } }, _count: { _all: true } }),
+    db.ticket.groupBy({ by: ['eventId'], where: { eventId: { in: ids } }, _sum: { quantity: true } }),
+    db.payment.groupBy({ by: ['eventId'], where: { ...EXCLUDE_DONATION_LEGS, eventId: { in: ids } }, _sum: { amount: true } }),
+    // People checked in (a group scan can let several in at once), per event through the ticket.
+    Promise.all(ids.map(async eventId => ({ eventId, n: (await db.ticketUsage.aggregate({ where: { ticket: { eventId } }, _sum: { quantityRedeemed: true } }))._sum.quantityRedeemed || 0 }))),
+  ]) : [[], [], [], []];
+  const map = (rows, pick) => new Map(rows.map(r => [r.eventId, pick(r)]));
+  const regBy = map(regs, r => r._count._all);
+  const ticketBy = map(tickets, r => r._sum.quantity || 0);
+  const incomeBy = map(income, r => r._sum.amount || 0);
+  const usageBy = map(usages, r => r.n);
+
+  const rows = events.map(e => {
+    const scans = usageBy.get(e.id) || 0;
+    const sessions = e.scheduleType === 'sessions' ? e._count.sessions : 0;
+    const t = ticketBy.get(e.id) || 0;
+    const checkedIn = sessions > 0 ? Math.round(scans / sessions) : scans;
+    return {
+      eventId: e.id, title: e.title, startDate: e.startDate, endDate: e.endDate, campus: e.campus, isActive: e.isActive,
+      sessions,
+      registrations: regBy.get(e.id) || 0,
+      tickets: t,
+      income: Math.round((incomeBy.get(e.id) || 0) * 100) / 100,
+      checkedIn,
+      attendanceRate: t > 0 ? Math.min(100, Math.round((checkedIn / t) * 100)) : null,
+    };
+  });
+  return { series, events: withChanges(rows) };
+}
+
+// ─── Privacy ─────────────────────────────────────────────────────────────────
+
+/** Series someone follows, for "Download my data". */
+async function exportFollows(userId, db = prisma) {
+  const rows = await db.seriesFollow.findMany({ where: { userId }, orderBy: { createdAt: 'asc' }, select: { createdAt: true, series: { select: { name: true } } } });
+  return rows.map(r => ({ series: r.series.name, since: r.createdAt }));
+}
+
+module.exports = {
+  publicEventWhere, cleanSeriesInput, seriesForEvent, nextInSeries, splitEvents,
+  follow, unfollow, runAnnounceJob, announcementEmail, exportFollows, seriesError, withChanges, compareSeries,
+};

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,
+};

backend/src/utils/webhooks.js

@@ -0,0 +1,391 @@
+/**
+ * Outbound webhooks (1.48.0): admins add endpoints (Site settings → Webhooks) and choose event
+ * types; what happens here is POSTed to them as JSON, signed with the endpoint's secret.
+ *
+ * - Events are noticed in one place, a Prisma client extension (config/db.js), so every path that
+ *   creates a registration, marks it paid, records a payment, checks a ticket in… is covered.
+ * - `notice` only queues (in memory); about a second later `flush` reads the record again — a
+ *   transaction that rolled back, or a status that changed back, sends nothing — builds the
+ *   payload and stores one WebhookDelivery per endpoint that wants the type, then sends them.
+ * - Sending: `X-CrossEvents-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">`
+ *   (like Stripe), 10 s timeout, redirects not followed, 2xx = delivered. Failures are retried
+ *   after 1 min, 5 min, 30 min, 2 h and 12 h, then marked failed (Resend on the delivery log).
+ * - Only https URLs on public addresses (no SSRF into the server's own network), unless
+ *   WEBHOOKS_ALLOW_PRIVATE=true (local testing).
+ * - Never sent: kids check-in and volunteer tickets (children's data stays here).
+ * - Deliveries hold personal information, so they're kept 30 days and removed with an account.
+ */
+
+const crypto = require('crypto');
+const dns = require('dns').promises;
+const net = require('net');
+const prisma = require('../config/db');
+const { encrypt, decrypt } = require('./encryption');
+
+const EVENT_TYPES = [
+  { type: 'registration.created', label: 'Registration made', description: 'Someone registers (online, at the door, by staff or with a season pass).' },
+  { type: 'registration.paid', label: 'Registration paid', description: 'A registration is paid in full — or made free.' },
+  { type: 'registration.cancelled', label: 'Registration cancelled', description: 'A registration is cancelled.' },
+  { type: 'payment.received', label: 'Payment received', description: 'Any payment or donation is recorded (online or by staff).' },
+  { type: 'payment.refunded', label: 'Payment refunded', description: 'A refund is recorded.' },
+  { type: 'ticket.checked_in', label: 'Ticket checked in', description: 'A ticket is scanned or ticked present.' },
+  { type: 'user.created', label: 'Account created', description: 'A new account is made.' },
+  { type: 'event.published', label: 'Event published', description: 'An event becomes public (made active and not hidden).' },
+];
+const TYPES = new Set(EVENT_TYPES.map(t => t.type));
+
+// What `data` looks like for each type — shown in Site settings → Webhooks so whoever builds the
+// receiving side knows what arrives. tests/webhooks.test.js checks these match buildPayload.
+const EXAMPLE_EVENT = { id: 'c1a2b3c4-0000-4000-8000-000000000001', title: 'Youth Camp 2026', startDate: '2026-12-04T16:00:00.000Z', endDate: '2026-12-06T12:00:00.000Z' };
+const EXAMPLE_PERSON = { id: 'u1a2b3c4-0000-4000-8000-000000000002', name: 'Thandi Mokoena', email: 'thandi@example.com', phone: '+27821234567' };
+const exampleRegistration = (status, amountPaid) => ({
+  registration: {
+    id: 'r1a2b3c4-0000-4000-8000-000000000003', status, createdAt: '2026-10-29T08:15:00.000Z', totalDue: 1200, amountPaid,
+    seasonPassPurchaseId: null,
+    items: [{ ticket: 'Camper', variant: 'Bunk bed', quantity: 2, unitPrice: 600 }],
+  },
+  event: EXAMPLE_EVENT,
+  person: EXAMPLE_PERSON,
+});
+const examplePayment = (amount) => ({
+  payment: { id: 'p1a2b3c4-0000-4000-8000-000000000004', amount, method: 'card', provider: 'yoco', isDonation: false, registrationId: 'r1a2b3c4-0000-4000-8000-000000000003', createdAt: '2026-10-29T08:16:00.000Z' },
+  event: EXAMPLE_EVENT,
+  person: EXAMPLE_PERSON,
+});
+const EXAMPLES = {
+  'registration.created': exampleRegistration('pending', 0),
+  'registration.paid': exampleRegistration('paid', 1200),
+  'registration.cancelled': exampleRegistration('cancelled', 0),
+  'payment.received': examplePayment(1200),
+  // Refunds are recorded as negative payments.
+  'payment.refunded': examplePayment(-600),
+  'ticket.checked_in': {
+    checkIn: { id: 't1a2b3c4-0000-4000-8000-000000000005', scannedAt: '2026-12-04T16:20:00.000Z', people: 1, manual: false, offline: false, session: { id: 's1a2b3c4-0000-4000-8000-000000000006', label: 'Friday evening', startsAt: '2026-12-04T16:00:00.000Z' } },
+    ticket: { id: 'k1a2b3c4-0000-4000-8000-000000000007', registrationOptionId: 'o1a2b3c4-0000-4000-8000-000000000008', holderName: 'Thandi Mokoena' },
+    event: EXAMPLE_EVENT,
+    person: EXAMPLE_PERSON,
+  },
+  'user.created': { person: { ...EXAMPLE_PERSON, role: 'user', createdAt: '2026-10-29T08:10:00.000Z' } },
+  'event.published': {
+    event: {
+      ...EXAMPLE_EVENT, description: 'A weekend away for grades 8–12.', location: 'Camp Joy, Magaliesburg', price: 600,
+      goLiveAt: '2026-10-29T06:00:00.000Z', url: 'https://events.example.org/events/c1a2b3c4-0000-4000-8000-000000000001',
+      campus: { name: 'North', slug: 'north' }, series: null,
+    },
+  },
+};
+for (const t of EVENT_TYPES) t.example = EXAMPLES[t.type];
+
+const RETRY_AFTER_MS = [60e3, 5 * 60e3, 30 * 60e3, 2 * 3600e3, 12 * 3600e3];
+const MAX_ATTEMPTS = RETRY_AFTER_MS.length + 1;
+const KEEP_DAYS = 30;
+const TIMEOUT_MS = 10000;
+
+function webhookError(message, statusCode = 400) {
+  const err = new Error(message);
+  err.statusCode = statusCode;
+  return err;
+}
+
+const allowPrivate = () => String(process.env.WEBHOOKS_ALLOW_PRIVATE || '').toLowerCase() === 'true';
+
+// ─── Endpoint addresses ──────────────────────────────────────────────────────
+
+/** Whether an IP address is private, loopback, link-local or otherwise not on the internet. */
+function isPrivateAddress(ip) {
+  if (net.isIPv4(ip)) {
+    const [a, b] = ip.split('.').map(Number);
+    return a === 10 || a === 127 || a === 0 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31)
+      || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127) || a >= 224;
+  }
+  if (net.isIPv6(ip)) {
+    const v = ip.toLowerCase();
+    if (v === '::1' || v === '::') return true;
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(v);
+    if (mapped) return isPrivateAddress(mapped[1]);
+    return /^f[cd]/.test(v) || /^fe[89ab]/.test(v);
+  }
+  return true;
+}
+
+/** A cleaned endpoint URL, or an error: https (http only for local testing), no user:password. */
+function cleanUrl(raw) {
+  let u;
+  try { u = new URL(String(raw || '').trim()); } catch { throw webhookError('Enter the full address, starting with https://'); }
+  if (u.protocol !== 'https:' && !(u.protocol === 'http:' && allowPrivate())) throw webhookError('The address must start with https://');
+  if (u.username || u.password) throw webhookError('Leave the user name and password out of the address');
+  if (!allowPrivate() && (u.hostname === 'localhost' || (net.isIP(u.hostname) && isPrivateAddress(u.hostname)))) {
+    throw webhookError('That address is on a private network — webhooks only go to public addresses');
+  }
+  return u.toString();
+}
+
+/** Refuses a host that resolves to a private address (checked at every send: DNS can change). */
+async function assertPublicHost(hostname) {
+  if (allowPrivate()) return;
+  const addresses = net.isIP(hostname) ? [{ address: hostname }] : await dns.lookup(hostname, { all: true });
+  if (!addresses.length || addresses.some(a => isPrivateAddress(a.address))) {
+    throw webhookError(`${hostname} points to a private network address`);
+  }
+}
+
+// ─── Signing ─────────────────────────────────────────────────────────────────
+
+const newSecret = () => `whsec_${crypto.randomBytes(24).toString('base64url')}`;
+
+/** The signature header for a body: t=<seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">. */
+function signatureHeader(secret, body, at = Date.now()) {
+  const t = Math.floor(at / 1000);
+  const v1 = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
+  return `t=${t},v1=${v1}`;
+}
+
+// ─── Endpoints (cached for `notice`) ─────────────────────────────────────────
+
+let endpointCache = null;
+let endpointCacheAt = 0;
+async function activeEndpoints() {
+  if (!endpointCache || Date.now() - endpointCacheAt > 60e3) {
+    endpointCache = await prisma.webhookEndpoint.findMany({ where: { isActive: true }, select: { id: true, events: true } });
+    endpointCacheAt = Date.now();
+  }
+  return endpointCache;
+}
+function forgetEndpoints() { endpointCache = null; }
+
+// ─── Noticing events ─────────────────────────────────────────────────────────
+
+const queue = [];
+let flushTimer = null;
+const FLUSH_DELAY_MS = 1500;
+
+/**
+ * Something happened (from the Prisma extension). Queued and checked again shortly; never throws.
+ * `ref` is the record's id.
+ */
+function notice(type, ref) {
+  if (!TYPES.has(type) || !ref) return;
+  if (String(process.env.WEBHOOKS_ENABLED || 'true').toLowerCase() === 'false') return;
+  queue.push({ type, ref, at: new Date() });
+  if (!flushTimer) {
+    flushTimer = setTimeout(() => { flushTimer = null; flush().catch(e => console.warn('[webhooks] flush:', e?.message || e)); }, FLUSH_DELAY_MS);
+    flushTimer.unref?.();
+  }
+}
+
+/** Builds and stores the deliveries for what was noticed, then sends them. */
+async function flush() {
+  const items = queue.splice(0, queue.length);
+  if (!items.length) return [];
+  const endpoints = await activeEndpoints();
+  const made = [];
+  for (const item of items) {
+    const targets = endpoints.filter(e => e.events.includes(item.type));
+    if (!targets.length) continue;
+    let built;
+    try { built = await buildPayload(item.type, item.ref); } catch (e) { console.warn(`[webhooks] ${item.type} ${item.ref}:`, e?.message || e); continue; }
+    if (!built) continue;
+    const eventId = `evt_${crypto.randomUUID()}`;
+    const payload = { id: eventId, type: item.type, createdAt: item.at.toISOString(), data: built.data };
+    for (const ep of targets) {
+      made.push(await prisma.webhookDelivery.create({ data: { endpointId: ep.id, eventId, type: item.type, payload, userId: built.userId || null } }));
+    }
+  }
+  for (const d of made) await send(d.id).catch(e => console.warn('[webhooks] send:', e?.message || e));
+  return made;
+}
+
+// ─── Payloads ────────────────────────────────────────────────────────────────
+
+const frontendUrl = () => String(process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');
+const person = u => (u ? { id: u.id, name: u.name, email: u.email, phone: u.phoneNumber || null } : null);
+const eventRef = e => (e ? { id: e.id, title: e.title, startDate: e.startDate, endDate: e.endDate } : null);
+const reservedIds = e => new Set([e?.kidsOptionId, e?.volunteerOptionId].filter(Boolean));
+const EVENT_SELECT = { id: true, title: true, startDate: true, endDate: true, kidsOptionId: true, volunteerOptionId: true };
+const USER_SELECT = { id: true, name: true, email: true, phoneNumber: true };
+
+async function registrationData(id, status) {
+  const r = await prisma.registration.findUnique({
+    where: { id },
+    include: {
+      event: { select: EVENT_SELECT }, user: { select: USER_SELECT }, payments: true,
+      registrationOptions: { include: { eventOption: { select: { id: true, name: true } }, variant: { select: { name: true } }, tranches: true } },
+    },
+  });
+  if (!r || (status && r.status !== status)) return null;
+  // Kids check-in and volunteer places are internal (and can be about children): never sent.
+  const reserved = reservedIds(r.event);
+  if (r.registrationOptions.length && r.registrationOptions.every(o => reserved.has(o.eventOptionId))) return null;
+  const { computeRegistrationTotalDue } = require('./pricing');
+  const totalDue = Math.round(computeRegistrationTotalDue(r, new Date()) * 100) / 100;
+  const paid = Math.round(r.payments.reduce((s, p) => s + p.amount, 0) * 100) / 100;
+  return {
+    userId: r.userId,
+    data: {
+      registration: {
+        id: r.id, status: r.status, createdAt: r.createdAt, totalDue, amountPaid: paid,
+        seasonPassPurchaseId: r.seasonPassPurchaseId || null,
+        items: r.registrationOptions.filter(o => !reserved.has(o.eventOptionId)).map(o => ({ ticket: o.eventOption?.name, variant: o.variant?.name || null, quantity: o.quantity, unitPrice: o.priceSnapshot })),
+      },
+      event: eventRef(r.event),
+      person: person(r.user),
+    },
+  };
+}
+
+async function buildPayload(type, ref) {
+  switch (type) {
+    case 'registration.created': return registrationData(ref);
+    case 'registration.paid': return registrationData(ref, 'paid');
+    case 'registration.cancelled': return registrationData(ref, 'cancelled');
+    case 'payment.received':
+    case 'payment.refunded': {
+      const p = await prisma.payment.findUnique({ where: { id: ref }, include: { user: { select: USER_SELECT }, event: { select: EVENT_SELECT } } });
+      if (!p) return null;
+      return {
+        userId: p.userId,
+        data: {
+          payment: { id: p.id, amount: p.amount, method: p.method, provider: p.provider || null, isDonation: p.isDonation, registrationId: p.registrationId, createdAt: p.createdAt },
+          event: eventRef(p.event),
+          person: person(p.user),
+        },
+      };
+    }
+    case 'ticket.checked_in': {
+      const u = await prisma.ticketUsage.findUnique({
+        where: { id: ref },
+        include: {
+          session: { select: { id: true, label: true, startsAt: true } },
+          ticket: { include: { event: { select: EVENT_SELECT }, user: { select: USER_SELECT }, holder: { select: USER_SELECT }, attendee: { select: { name: true } }, registrationOption: { select: { eventOptionId: true } } } },
+        },
+      });
+      if (!u) return null;
+      if (reservedIds(u.ticket.event).has(u.ticket.registrationOption?.eventOptionId)) return null;
+      // A transferred ticket belongs to its holder now.
+      const who = u.ticket.holder || u.ticket.user;
+      return {
+        userId: who?.id || u.ticket.userId,
+        data: {
+          checkIn: { id: u.id, scannedAt: u.scannedAt, people: u.quantityRedeemed, manual: u.manual, offline: u.offline, session: u.session || null },
+          ticket: { id: u.ticket.id, registrationOptionId: u.ticket.registrationOptionId, holderName: u.ticket.attendee?.name || who?.name || null },
+          event: eventRef(u.ticket.event),
+          person: person(who),
+        },
+      };
+    }
+    case 'user.created': {
+      const user = await prisma.user.findUnique({ where: { id: ref }, select: { ...USER_SELECT, role: true, createdAt: true } });
+      if (!user) return null;
+      return { userId: user.id, data: { person: { ...person(user), role: user.role, createdAt: user.createdAt } } };
+    }
+    case 'event.published': {
+      const e = await prisma.event.findUnique({
+        where: { id: ref },
+        select: { ...EVENT_SELECT, description: true, location: true, price: true, isActive: true, isHidden: true, goLiveAt: true, campus: { select: { name: true, slug: true } }, series: { select: { name: true, slug: true } } },
+      });
+      if (!e || !e.isActive || e.isHidden) return null;
+      return {
+        userId: null,
+        data: {
+          event: {
+            id: e.id, title: e.title, description: e.description, startDate: e.startDate, endDate: e.endDate, location: e.location,
+            price: e.price, goLiveAt: e.goLiveAt, url: `${frontendUrl()}/events/${e.id}`, campus: e.campus || null, series: e.series || null,
+          },
+        },
+      };
+    }
+    default: return null;
+  }
+}
+
+// ─── Sending ─────────────────────────────────────────────────────────────────
+
+/** The wait before the next try after `attempts` failed tries, or null when it's given up. Pure. */
+function retryDelay(attempts) {
+  return attempts < MAX_ATTEMPTS ? RETRY_AFTER_MS[attempts - 1] : null;
+}
+
+/** POSTs one delivery (claimed first, so two workers never send it twice). */
+async function send(deliveryId) {
+  const claimed = await prisma.webhookDelivery.updateMany({ where: { id: deliveryId, status: { in: ['pending', 'retrying'] } }, data: { status: 'sending', nextAttemptAt: new Date() } });
+  if (!claimed.count) return null;
+  const d = await prisma.webhookDelivery.findUnique({ where: { id: deliveryId }, include: { endpoint: true } });
+  const attempts = d.attempts + 1;
+  const body = JSON.stringify(d.payload);
+  let statusCode = null;
+  let error = null;
+  try {
+    if (!d.endpoint.isActive) throw webhookError('The endpoint is switched off');
+    const url = new URL(cleanUrl(d.endpoint.url));
+    await assertPublicHost(url.hostname);
+    const res = await fetch(url, {
+      method: 'POST',
+      redirect: 'manual',
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': 'CrossEvents-Webhooks/1',
+        'X-CrossEvents-Event': d.type,
+        'X-CrossEvents-Delivery': d.id,
+        'X-CrossEvents-Signature': signatureHeader(decrypt(d.endpoint.secret), body),
+      },
+      body,
+    });
+    statusCode = res.status;
+    if (res.status < 200 || res.status >= 300) error = `Answered ${res.status}${res.status >= 300 && res.status < 400 ? ' (redirects are not followed)' : ''}`;
+  } catch (e) {
+    error = e?.name === 'TimeoutError' ? `No answer within ${TIMEOUT_MS / 1000} seconds` : (e?.message || String(e));
+  }
+  const now = new Date();
+  const ok = !error;
+  const wait = ok ? null : retryDelay(attempts);
+  const updated = await prisma.webhookDelivery.update({
+    where: { id: d.id },
+    data: {
+      attempts, lastStatusCode: statusCode, lastError: error ? String(error).slice(0, 500) : null,
+      status: ok ? 'succeeded' : wait ? 'retrying' : 'failed',
+      deliveredAt: ok ? now : null,
+      nextAttemptAt: wait ? new Date(now.getTime() + wait) : now,
+    },
+  });
+  await prisma.webhookEndpoint.update({ where: { id: d.endpointId }, data: ok ? { lastSuccessAt: now } : { lastFailureAt: now } }).catch(() => {});
+  return updated;
+}
+
+/** The `webhooks` job: sends what's due, picks up sends cut off by a restart, prunes old deliveries. */
+async function runJob(now = new Date()) {
+  // A send is claimed with nextAttemptAt = now; one still "sending" 5 minutes later was cut off.
+  await prisma.webhookDelivery.updateMany({ where: { status: 'sending', nextAttemptAt: { lt: new Date(now.getTime() - 5 * 60e3) } }, data: { status: 'retrying' } });
+  const due = await prisma.webhookDelivery.findMany({ where: { status: { in: ['pending', 'retrying'] }, nextAttemptAt: { lte: now } }, orderBy: { nextAttemptAt: 'asc' }, take: 100, select: { id: true } });
+  let sent = 0;
+  let failed = 0;
+  for (const { id } of due) {
+    const r = await send(id).catch(() => null);
+    if (r?.status === 'succeeded') sent++;
+    else if (r) failed++;
+  }
+  const pruned = await prisma.webhookDelivery.deleteMany({ where: { createdAt: { lt: new Date(now.getTime() - KEEP_DAYS * 864e5) } } });
+  return { due: due.length, sent, failed, pruned: pruned.count };
+}
+
+/** Sends a delivery again now (a fresh try, whatever happened before). */
+async function resend(deliveryId) {
+  const d = await prisma.webhookDelivery.findUnique({ where: { id: deliveryId }, select: { id: true } });
+  if (!d) throw webhookError('Delivery not found', 404);
+  await prisma.webhookDelivery.update({ where: { id: d.id }, data: { status: 'pending', attempts: 0, nextAttemptAt: new Date() } });
+  return send(d.id);
+}
+
+/** A "webhook.test" delivery to one endpoint, sent at once. */
+async function sendTest(endpointId) {
+  const eventId = `evt_${crypto.randomUUID()}`;
+  const payload = { id: eventId, type: 'webhook.test', createdAt: new Date().toISOString(), data: { message: 'A test from Cross Events. If you can read this, the webhook works.' } };
+  const d = await prisma.webhookDelivery.create({ data: { endpointId, eventId, type: 'webhook.test', payload } });
+  return send(d.id);
+}
+
+module.exports = {
+  EVENT_TYPES, TYPES, MAX_ATTEMPTS, KEEP_DAYS,
+  isPrivateAddress, cleanUrl, assertPublicHost, newSecret, signatureHeader, encrypt,
+  notice, flush, buildPayload, retryDelay, send, runJob, resend, sendTest, forgetEndpoints, webhookError,
+};

backend/src/v2/deprecation.ts

@@ -0,0 +1,84 @@
+import type { RequestHandler } from 'express';
+
+/**
+ * v1 endpoints that have a v2 replacement say so (1.51.3): a `Deprecation` header (RFC 9745,
+ * the date v2 covered them) and `Link: <…>; rel="successor-version"` pointing at the v2
+ * endpoint. v1 keeps working until 2.0; endpoints without a v2 version get no header yet.
+ */
+
+// When these v1 endpoints got their v2 replacement (1.51.3's release day).
+const DEPRECATED_AT = Math.floor(Date.UTC(2026, 9, 29) / 1000);
+
+type Successor = { method: string; v1: RegExp; v2: (m: RegExpMatchArray) => string };
+
+const SUCCESSORS: Successor[] = [
+  { method: 'GET', v1: /^\/api\/events\/?$/, v2: () => '/api/v2/events' },
+  // v1's event detail is the full record (v2's /events/{id} is the public summary).
+  { method: 'GET', v1: /^\/api\/events\/([^/]+)$/, v2: m => `/api/v2/events/${m[1]}/full` },
+  // 1.51.8: the rest of the events area
+  { method: 'GET', v1: /^\/api\/events\/([^/]+)\/ics$/, v2: m => `/api/v2/events/${m[1]}/calendar.ics` },
+  { method: 'GET', v1: /^\/api\/events\/by-alias\/([^/]+)$/, v2: m => `/api/v2/events/by-alias/${m[1]}` },
+  { method: 'POST', v1: /^\/api\/events\/([^/]+)\/options$/, v2: m => `/api/v2/events/${m[1]}/ticket-options` },
+  { method: 'PUT', v1: /^\/api\/events\/options\/([^/]+)$/, v2: m => `/api/v2/ticket-options/${m[1]}` },
+  { method: 'DELETE', v1: /^\/api\/events\/options\/([^/]+)$/, v2: m => `/api/v2/ticket-options/${m[1]}` },
+  { method: 'POST', v1: /^\/api\/events\/options\/([^/]+)\/variants$/, v2: m => `/api/v2/ticket-options/${m[1]}/variants` },
+  { method: 'PUT', v1: /^\/api\/events\/variants\/([^/]+)$/, v2: m => `/api/v2/variants/${m[1]}` },
+  { method: 'DELETE', v1: /^\/api\/events\/variants\/([^/]+)$/, v2: m => `/api/v2/variants/${m[1]}` },
+  { method: 'GET', v1: /^\/api\/events\/attachments\/status$/, v2: () => '/api/v2/attachments/status' },
+  { method: 'POST', v1: /^\/api\/events\/attachments\/sync$/, v2: () => '/api/v2/attachments/sync' },
+  { method: 'GET', v1: /^\/api\/events\/([^/]+)\/attachments$/, v2: m => `/api/v2/events/${m[1]}/attachments` },
+  { method: 'POST', v1: /^\/api\/events\/([^/]+)\/attachments$/, v2: m => `/api/v2/events/${m[1]}/attachments` },
+  { method: 'DELETE', v1: /^\/api\/events\/([^/]+)\/attachments\/([^/]+)$/, v2: m => `/api/v2/events/${m[1]}/attachments/${m[2]}` },
+  { method: 'GET', v1: /^\/api\/sections\/?$/, v2: () => '/api/v2/sections' },
+  { method: 'POST', v1: /^\/api\/sections\/?$/, v2: () => '/api/v2/sections' },
+  { method: 'PUT', v1: /^\/api\/sections\/([^/]+)$/, v2: m => `/api/v2/sections/${m[1]}` },
+  { method: 'DELETE', v1: /^\/api\/sections\/([^/]+)$/, v2: m => `/api/v2/sections/${m[1]}` },
+  { method: 'GET', v1: /^\/api\/events\/([^/]+)\/costs$/, v2: m => `/api/v2/events/${m[1]}/costs` },
+  { method: 'POST', v1: /^\/api\/events\/([^/]+)\/costs$/, v2: m => `/api/v2/events/${m[1]}/costs` },
+  { method: 'PUT', v1: /^\/api\/costs\/([^/]+)$/, v2: m => `/api/v2/costs/${m[1]}` },
+  { method: 'DELETE', v1: /^\/api\/costs\/([^/]+)$/, v2: m => `/api/v2/costs/${m[1]}` },
+  { method: 'POST', v1: /^\/api\/uploads\/(event-image|logo|favicon)$/, v2: m => `/api/v2/uploads/${m[1]}` },
+  // 1.51.7: setting events up
+  { method: 'GET', v1: /^\/api\/events\/all$/, v2: () => '/api/v2/events/manage' },
+  { method: 'POST', v1: /^\/api\/events\/?$/, v2: () => '/api/v2/events' },
+  { method: 'PUT', v1: /^\/api\/events\/([^/]+)$/, v2: m => `/api/v2/events/${m[1]}` },
+  { method: 'DELETE', v1: /^\/api\/events\/([^/]+)$/, v2: m => `/api/v2/events/${m[1]}` },
+  { method: 'POST', v1: /^\/api\/events\/([^/]+)\/copy-from$/, v2: m => `/api/v2/events/${m[1]}/copy-from` },
+  { method: 'GET', v1: /^\/api\/events\/([^/]+)\/notify-recipients$/, v2: m => `/api/v2/events/${m[1]}/notify-recipients` },
+  { method: 'PUT', v1: /^\/api\/events\/([^/]+)\/notify-recipients$/, v2: m => `/api/v2/events/${m[1]}/notify-recipients` },
+  { method: 'GET', v1: /^\/api\/users\/profile$/, v2: () => '/api/v2/me' },
+  { method: 'PUT', v1: /^\/api\/users\/profile$/, v2: () => '/api/v2/me' },
+  { method: 'POST', v1: /^\/api\/users\/?$/, v2: () => '/api/v2/auth/signup' },
+  { method: 'POST', v1: /^\/api\/users\/login$/, v2: () => '/api/v2/auth/login' },
+  { method: 'POST', v1: /^\/api\/users\/login\/2fa$/, v2: () => '/api/v2/auth/login/code' },
+  { method: 'GET', v1: /^\/api\/registrations\/myregistrations$/, v2: () => '/api/v2/me/registrations' },
+  { method: 'POST', v1: /^\/api\/registrations\/?$/, v2: () => '/api/v2/registrations' },
+  { method: 'DELETE', v1: /^\/api\/registrations\/([^/]+)$/, v2: m => `/api/v2/registrations/${m[1]}/cancel` },
+  { method: 'POST', v1: /^\/api\/payments\/checkout$/, v2: () => '/api/v2/registrations/{id}/checkout' },
+  { method: 'GET', v1: /^\/api\/tickets\/scan-preview\/([^/]+)$/, v2: m => `/api/v2/checkin/${m[1]}` },
+  { method: 'POST', v1: /^\/api\/tickets\/scan\/([^/]+)$/, v2: m => `/api/v2/checkin/${m[1]}` },
+];
+
+// GET /api/events/all isn't a single event.
+const NOT_AN_EVENT_ID = new Set(['all']);
+
+/** The v2 successor of a v1 request, if it has one. Pure; exported for tests. */
+export function successorOf(method: string, path: string): string | null {
+  for (const s of SUCCESSORS) {
+    if (s.method !== method) continue;
+    const m = path.match(s.v1);
+    if (!m) continue;
+    if (s.v1.source.startsWith('^\\/api\\/events\\/(') && NOT_AN_EVENT_ID.has(m[1])) continue;
+    return s.v2(m);
+  }
+  return null;
+}
+
+export const deprecationHeaders: RequestHandler = (req, res, next) => {
+  const successor = successorOf(req.method, req.originalUrl.split('?')[0]);
+  if (successor) {
+    res.setHeader('Deprecation', `@${DEPRECATED_AT}`);
+    res.setHeader('Link', `<${successor}>; rel="successor-version"`);
+  }
+  next();
+};

backend/src/v2/errors.ts

@@ -0,0 +1,105 @@
+import type { ErrorRequestHandler, RequestHandler } from 'express';
+import { ZodError } from 'zod';
+
+/**
+ * /api/v2 errors all look the same:
+ *   { "error": { "code": "VALIDATION_FAILED", "message": "…", "fields": { "limit": "…" } } }
+ * `code` is stable (clients switch on it), `message` is for people, `fields` only on validation.
+ */
+export type ErrorCode =
+  | 'VALIDATION_FAILED'
+  | 'UNAUTHENTICATED'
+  | 'FORBIDDEN'
+  | 'NOT_FOUND'
+  | 'CONFLICT'
+  | 'RATE_LIMITED'
+  | 'READ_ONLY'
+  | 'INTERNAL';
+
+export const ERROR_STATUS: Record<ErrorCode, number> = {
+  VALIDATION_FAILED: 400,
+  UNAUTHENTICATED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  RATE_LIMITED: 429,
+  READ_ONLY: 403,
+  INTERNAL: 500,
+};
+
+export class ApiError extends Error {
+  readonly code: ErrorCode;
+  readonly status: number;
+  readonly fields?: Record<string, string>;
+
+  constructor(code: ErrorCode, message: string, fields?: Record<string, string>) {
+    super(message);
+    this.code = code;
+    this.status = ERROR_STATUS[code];
+    this.fields = fields;
+  }
+}
+
+export const notFound = (what = 'That'): ApiError => new ApiError('NOT_FOUND', `${what} wasn't found.`);
+
+/** "limit" or "items.0.quantity" → the first problem with it. */
+export function zodFields(err: ZodError): Record<string, string> {
+  const fields: Record<string, string> = {};
+  for (const issue of err.issues) {
+    const key = issue.path.length ? issue.path.join('.') : '_';
+    if (!fields[key]) fields[key] = issue.message;
+  }
+  return fields;
+}
+
+const STATUS_CODE: Record<number, ErrorCode> = { 400: 'VALIDATION_FAILED', 401: 'UNAUTHENTICATED', 403: 'FORBIDDEN', 404: 'NOT_FOUND', 409: 'CONFLICT', 423: 'READ_ONLY', 429: 'RATE_LIMITED' };
+const PRISMA_CODE: Record<string, ErrorCode> = { P2002: 'CONFLICT', P2025: 'NOT_FOUND', P2003: 'CONFLICT' };
+
+type LegacyError = Error & { statusCode?: number; status?: number; code?: string };
+
+/** Turns anything thrown (ApiError, zod, Prisma, the v1 auth middleware's errors) into the v2 shape. */
+export function toApiError(err: unknown, responseStatus: number): ApiError {
+  if (err instanceof ApiError) return err;
+  if (err instanceof ZodError) return new ApiError('VALIDATION_FAILED', 'Some of what was sent is not valid.', zodFields(err));
+  const e = (err || {}) as LegacyError;
+  if (typeof e.code === 'string' && PRISMA_CODE[e.code]) {
+    return new ApiError(PRISMA_CODE[e.code], e.code === 'P2002' ? 'A record with that value already exists.' : e.code === 'P2025' ? 'Record not found.' : 'A related record prevents this.');
+  }
+  // The shared v1 middleware (protect, staff…) sets res.status() and passes an Error;
+  // utils throw errors with statusCode. Those messages are written for people already.
+  const status = e.statusCode || e.status || (responseStatus >= 400 ? responseStatus : 500);
+  const code = STATUS_CODE[status];
+  if (code) return new ApiError(code, e.message || 'Request failed.');
+  return new ApiError('INTERNAL', 'Something went wrong on the server.');
+}
+
+export const errorHandler: ErrorRequestHandler = (err, req, res, _next) => {
+  const apiErr = toApiError(err, res.statusCode);
+  if (apiErr.code === 'INTERNAL') console.error('[api/v2]', req.method, req.originalUrl, err);
+  res.status(apiErr.status).json({ error: { code: apiErr.code, message: apiErr.message, ...(apiErr.fields ? { fields: apiErr.fields } : {}) } });
+};
+
+export const notFoundHandler: RequestHandler = (_req, _res, next) => next(new ApiError('NOT_FOUND', 'There is no such API endpoint.'));
+
+// v1-style codes from shared middleware, kept as the v2 error's `reason`.
+const READ_ONLY_REASONS = new Set(['IMPERSONATION_READ_ONLY', 'LICENCE_READ_ONLY']);
+
+/**
+ * Mounted in front of everything on /api/v2: middleware shared with v1 (rate limits, the
+ * read-only guards, the auth checks, campus refusals) answers `{ message, code? }`; on v2 that
+ * becomes `{ error: { code, message, reason? } }`, where `reason` is the specific old code
+ * (e.g. TWO_FACTOR_REQUIRED, LICENCE_READ_ONLY, OTHER_CAMPUS).
+ */
+export const legacyErrorsToV2: RequestHandler = (_req, res, next) => {
+  const json = res.json.bind(res);
+  res.json = (body?: unknown) => {
+    const b = body as { message?: unknown; code?: unknown; error?: unknown } | null;
+    if (res.statusCode >= 400 && b && typeof b === 'object' && !('error' in b) && typeof b.message === 'string') {
+      const reason = typeof b.code === 'string' ? b.code : undefined;
+      const code: ErrorCode = reason && READ_ONLY_REASONS.has(reason) ? 'READ_ONLY' : STATUS_CODE[res.statusCode] || (res.statusCode >= 500 ? 'INTERNAL' : 'VALIDATION_FAILED');
+      return json({ error: { code, message: b.message, ...(reason ? { reason } : {}) } });
+    }
+    return json(body);
+  };
+  next();
+};

backend/src/v2/index.ts

@@ -0,0 +1,99 @@
+import express, { Router } from 'express';
+import path from 'path';
+import { mount, routes } from './route';
+import { buildOpenApi } from './openapi';
+import { errorHandler, notFoundHandler } from './errors';
+import auth from '../middleware/authMiddleware';
+// Resources: importing one registers its routes.
+// eventsManage first: /events/manage must match before /events/:id.
+import './resources/eventsManage';
+import './resources/eventDetails';
+import './resources/setup';
+import './resources/events';
+import './resources/me';
+import './resources/registrations';
+import './resources/checkin';
+import './resources/auth';
+
+const pkg = require('../../package.json') as { version: string };
+
+/** /api/v2 — see route.ts for how endpoints are declared, openapi.ts for the docs. */
+export function v2Router(): Router {
+  const router = express.Router();
+
+  // The API description is for the people building on it (admins), like /docs.
+  router.get('/openapi.json', auth.protect, auth.admin, (_req, res) => {
+    res.json(buildOpenApi({ version: pkg.version }));
+  });
+
+  mount(router, routes);
+  router.use(notFoundHandler);
+  router.use(errorHandler);
+  return router;
+}
+
+/**
+ * /docs/v2: Swagger UI (served from swagger-ui-dist, nothing from a CDN). The page itself is
+ * public; it asks for an admin token and uses it to load openapi.json and to try requests.
+ */
+export function v2DocsRouter(): Router {
+  const router = express.Router();
+  const assets = path.dirname(require.resolve('swagger-ui-dist/package.json'));
+  router.use('/assets', express.static(assets, { index: false, maxAge: '1d' }));
+  router.get('/', (_req, res) => {
+    res.type('html').send(DOCS_HTML);
+  });
+  return router;
+}
+
+const DOCS_HTML = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Cross Events API v2</title>
+  <link rel="stylesheet" href="/docs/v2/assets/swagger-ui.css">
+  <style>
+    body { margin: 0; font-family: system-ui, sans-serif; }
+    #login { max-width: 40rem; margin: 3rem auto; padding: 0 1rem; }
+    #login input { width: 100%; padding: .5rem; font: inherit; border: 1px solid #9ca3af; border-radius: 6px; box-sizing: border-box; }
+    #login button { margin-top: .75rem; padding: .5rem 1rem; font: inherit; background: #1d4ed8; color: #fff; border: 0; border-radius: 6px; cursor: pointer; }
+    #login .err { color: #b91c1c; margin-top: .5rem; }
+  </style>
+</head>
+<body>
+  <main id="login" hidden>
+    <h1>Cross Events API v2</h1>
+    <p>The API reference is for admins. Paste your admin token (after signing in, it's under <code>hope_events_token</code> in the browser's local storage).</p>
+    <label for="token">Admin token</label>
+    <input id="token" autocomplete="off">
+    <button id="go" type="button">Show the API</button>
+    <p class="err" id="err" role="alert"></p>
+  </main>
+  <div id="ui"></div>
+  <script src="/docs/v2/assets/swagger-ui-bundle.js"></script>
+  <script>
+  (function () {
+    var params = new URLSearchParams(location.search);
+    var token = params.get('token') || sessionStorage.getItem('v2docs_token') || localStorage.getItem('hope_events_token') || '';
+    function show(t) {
+      fetch('/api/v2/openapi.json', { headers: { Authorization: 'Bearer ' + t } }).then(function (r) {
+        if (!r.ok) return r.json().then(function (b) { throw new Error((b.error && b.error.message) || r.statusText); });
+        return r.json();
+      }).then(function (spec) {
+        sessionStorage.setItem('v2docs_token', t);
+        if (params.has('token')) history.replaceState(null, '', location.pathname);
+        document.getElementById('login').hidden = true;
+        var ui = SwaggerUIBundle({ spec: spec, dom_id: '#ui', deepLinking: true, persistAuthorization: false });
+        ui.preauthorizeApiKey('bearerAuth', t);
+      }).catch(function (e) {
+        document.getElementById('login').hidden = false;
+        document.getElementById('err').textContent = t ? 'That token did not work: ' + e.message : '';
+      });
+    }
+    document.getElementById('go').addEventListener('click', function () { show(document.getElementById('token').value.trim()); });
+    show(token);
+  })();
+  </script>
+</body>
+</html>`;

backend/src/v2/legacy.ts

@@ -0,0 +1,32 @@
+/**
+ * Typed doors into the JavaScript side of the backend. TypeScript infers loose types from the
+ * .js files (the Prisma client is built by a function, helpers have defaulted options), so v2
+ * code imports them from here instead. When a module is converted to TypeScript, its line here
+ * goes and callers import it directly.
+ */
+import type { PrismaClient } from '@prisma/client';
+
+// The client in config/db.js only adds query hooks (webhooks), so its models are PrismaClient's.
+export const prisma = require('../config/db') as PrismaClient;
+
+type CampusFilter = '' | 'all' | string;
+const campuses = require('../utils/campuses') as {
+  campusesEnabled(): Promise<boolean>;
+  resolveCampusFilter(value: string | undefined): Promise<CampusFilter>;
+  campusWhere(filter: CampusFilter, opts: { enabled: boolean; withAllCampuses?: boolean }): object;
+};
+export const { campusesEnabled, resolveCampusFilter, campusWhere } = campuses;
+
+export const { publicEventWhere } = require('../utils/series') as {
+  publicEventWhere(now?: Date): { isActive: true; isHidden: false; goLiveAt: { lte: Date } };
+};
+
+type OptionLike = { id: string; price: number; earlyBirdTiers?: unknown[] };
+export const { publicOptions } = require('../utils/volunteers') as {
+  publicOptions<O extends { id: string }>(event: { eventOptions?: O[]; kidsOptionId?: string | null; volunteerOptionId?: string | null }): O[];
+};
+
+export const { getEffectiveUnitPrice, computeRegistrationTotalDue } = require('../utils/pricing') as {
+  getEffectiveUnitPrice(option: OptionLike, referenceTime: Date | null, atTime: Date): number;
+  computeRegistrationTotalDue(registration: object, atTime: Date): number;
+};

backend/src/v2/openapi.ts

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import { routes as allRoutes, type AnyRoute, type Access } from './route';
+import { ERROR_STATUS } from './errors';
+
+/**
+ * The OpenAPI 3.1 document for /api/v2, built from the route declarations (route.ts), so it is
+ * always what the code does. Served at /api/v2/openapi.json, shown at /docs/v2.
+ */
+
+type JsonSchema = Record<string, unknown>;
+
+const toSchema = (schema: z.ZodType, io: 'input' | 'output'): JsonSchema => {
+  const { $schema: _drop, ...rest } = z.toJSONSchema(schema, { io, unrepresentable: 'any' }) as JsonSchema;
+  return rest;
+};
+
+const ACCESS_TEXT: Record<Access, string> = {
+  public: 'Anyone.',
+  optional: 'Anyone; signed-in staff may see more.',
+  user: 'Any signed-in person.',
+  staff: 'Staff, supervisors and admins.',
+  supervisor: 'Supervisors and admins.',
+  admin: 'Admins only.',
+};
+
+const errorSchema = {
+  type: 'object',
+  required: ['error'],
+  properties: {
+    error: {
+      type: 'object',
+      required: ['code', 'message'],
+      properties: {
+        code: { type: 'string', enum: Object.keys(ERROR_STATUS) },
+        message: { type: 'string' },
+        fields: { type: 'object', additionalProperties: { type: 'string' }, description: 'Per-field problems (VALIDATION_FAILED only)' },
+        reason: { type: 'string', description: 'A more specific cause when there is one, e.g. TWO_FACTOR_REQUIRED, IMPERSONATION_ENDED, LICENCE_READ_ONLY, OTHER_CAMPUS' },
+      },
+    },
+  },
+};
+
+const errorResponse = (description: string) => ({ description, content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } } });
+
+function parameters(def: AnyRoute) {
+  const out: JsonSchema[] = [];
+  const add = (schema: z.ZodType | undefined, where: 'path' | 'query') => {
+    if (!schema) return;
+    const json = toSchema(schema, 'input') as { properties?: Record<string, JsonSchema>; required?: string[] };
+    for (const [name, prop] of Object.entries(json.properties || {})) {
+      const { description, ...propSchema } = prop as JsonSchema & { description?: string };
+      out.push({ name, in: where, required: where === 'path' || (json.required || []).includes(name), ...(description ? { description } : {}), schema: propSchema });
+    }
+  };
+  add(def.params, 'path');
+  add(def.query, 'query');
+  return out;
+}
+
+export function buildOpenApi(opts: { version: string; serverUrl?: string; list?: AnyRoute[] }) {
+  const list = opts.list ?? allRoutes;
+  const paths: Record<string, Record<string, unknown>> = {};
+  for (const def of list) {
+    const path = def.path.replace(/:(\w+)/g, '{$1}');
+    const secured = def.access !== 'public' && def.access !== 'optional';
+    paths[path] ||= {};
+    paths[path][def.method] = {
+      tags: [def.tag],
+      summary: def.summary,
+      description: [def.description, `**Who:** ${ACCESS_TEXT[def.access]}`].filter(Boolean).join('\n\n'),
+      operationId: `${def.method}${path.replace(/[{}]/g, '').split('/').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('')}`,
+      ...(secured ? { security: [{ bearerAuth: [] }] } : def.access === 'optional' ? { security: [{}, { bearerAuth: [] }] } : {}),
+      parameters: parameters(def),
+      ...(def.upload
+        ? { requestBody: { required: true, content: { 'multipart/form-data': { schema: { type: 'object', required: [def.upload.field], properties: { [def.upload.field]: { type: 'string', format: 'binary', description: def.upload.description } } } } } } }
+        : def.body ? { requestBody: { required: true, content: { 'application/json': { schema: toSchema(def.body, 'input') } } } } : {}),
+      responses: {
+        [String(def.status ?? 200)]: def.file
+          ? { description: 'The file', content: { [def.file.contentType]: { schema: { type: 'string' } } } }
+          : { description: 'OK', content: { 'application/json': { schema: toSchema(def.response, 'output') } } },
+        ...(def.params || def.query || def.body ? { 400: errorResponse('Validation failed (VALIDATION_FAILED)') } : {}),
+        ...(secured ? { 401: errorResponse('Not signed in (UNAUTHENTICATED)') } : {}),
+        ...(secured && def.access !== 'user' ? { 403: errorResponse('Not allowed for this role (FORBIDDEN)') } : {}),
+        ...(def.params ? { 404: errorResponse('Not found (NOT_FOUND)') } : {}),
+      },
+    };
+  }
+  return {
+    openapi: '3.1.0',
+    info: {
+      title: 'Cross Events API',
+      version: opts.version,
+      description: [
+        'Version 2 of the Cross Events API. Every response is JSON:',
+        '- a single item is `{ "data": { … } }`;',
+        '- a list is `{ "data": [ … ], "meta": { "page", "limit", "total", "pages" } }`, paged with `?page=` and `?limit=` (at most 100);',
+        '- an error is `{ "error": { "code", "message", "fields"? } }` with a stable `code`.',
+        '',
+        'Dates are ISO 8601 in UTC; amounts are in rand. Sign in through the app and send the token as `Authorization: Bearer <token>`.',
+        'Version 1 (`/api/…`) keeps working while the app moves over; it will be removed in 2.0.',
+      ].join('\n'),
+    },
+    servers: [{ url: opts.serverUrl ?? '/api/v2' }],
+    tags: Array.from(new Set(list.map(r => r.tag))).map(name => ({ name })),
+    paths,
+    components: {
+      securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' } },
+      schemas: { Error: errorSchema },
+    },
+  };
+}

backend/src/v2/paging.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+/** `?page=2&limit=25` on every v2 list (limit 1–100, default 25). */
+export const pageQuery = z.object({
+  page: z.coerce.number().int().min(1).default(1).describe('Page number, from 1'),
+  limit: z.coerce.number().int().min(1).max(100).default(25).describe('Items per page (at most 100)'),
+});
+export type PageQuery = z.infer<typeof pageQuery>;
+
+export const pageMeta = z.object({
+  page: z.number().int(),
+  limit: z.number().int(),
+  total: z.number().int().describe('Items across all pages'),
+  pages: z.number().int().describe('Number of pages (at least 1)'),
+});
+
+/** The response shape of a v2 list: `{ data: [...], meta: { page, limit, total, pages } }`. */
+export const paged = <T extends z.ZodType>(item: T) => z.object({ data: z.array(item), meta: pageMeta });
+
+/** The response shape of a single v2 resource: `{ data: {...} }`. */
+export const single = <T extends z.ZodType>(item: T) => z.object({ data: item });
+
+/** Prisma's skip/take for a page. */
+export const skipTake = ({ page, limit }: PageQuery) => ({ skip: (page - 1) * limit, take: limit });
+
+export function pageOf<T>(data: T[], total: number, { page, limit }: PageQuery) {
+  return { data, meta: { page, limit, total, pages: Math.max(1, Math.ceil(total / limit)) } };
+}

backend/src/v2/resources/auth.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import type { Request } from 'express';
+import { defineRoute } from '../route';
+import { single } from '../paging';
+import { id } from '../schemas';
+import auth from '../../middleware/authMiddleware';
+import { signUp, logIn, verifyLoginCode, type Session } from '../../services/auth';
+
+const requestInfo = (req: Request) => {
+  const { getClientIp } = require('../../utils/requestUtils') as { getClientIp(req: unknown): string };
+  return { ip: getClientIp(req), userAgent: req.headers['user-agent'] };
+};
+
+const session = z.object({
+  status: z.literal('signed_in'),
+  token: z.string().describe('Send as `Authorization: Bearer <token>`'),
+  user: z.object({ id, name: z.string(), email: z.string(), role: z.enum(['admin', 'supervisor', 'staff', 'user']) }),
+  newsPromptPending: z.boolean().describe('Ask once whether they want News & announcements'),
+  noticePromptPending: z.union([z.literal(false), z.enum(['first', 'updated'])]).describe('A privacy notice they must accept: never accepted (first) or a newer version (updated)'),
+  deviceToken: z.string().optional().describe('With rememberDevice: send it with the next login to skip the code on this device'),
+});
+
+const toSession = (s: Session): z.input<typeof session> => ({
+  status: 'signed_in',
+  token: s.token,
+  user: { id: s.id, name: s.name, email: s.email, role: s.role as 'admin' | 'supervisor' | 'staff' | 'user' },
+  newsPromptPending: s.newsPromptPending,
+  noticePromptPending: s.noticePromptPending,
+  ...(s.deviceToken ? { deviceToken: s.deviceToken } : {}),
+});
+
+export const signup = defineRoute({
+  method: 'post',
+  path: '/auth/signup',
+  tag: 'Accounts',
+  summary: 'Create an account',
+  description: 'Signs the new account in straight away. `acceptTerms` must be true (the Terms of Use and Privacy Policy); `newsOptIn` is the unticked "News & announcements" box.',
+  access: 'public',
+  status: 201,
+  body: z.object({
+    name: z.string().trim().min(1).max(200),
+    email: z.email().max(200),
+    password: z.string().min(8).max(200),
+    phone: z.string().trim().max(40).optional(),
+    notificationPreference: z.enum(['email', 'whatsapp', 'both']).optional().describe('WhatsApp needs a valid South African number; otherwise email is used'),
+    newsOptIn: z.boolean().optional(),
+    acceptTerms: z.literal(true),
+  }),
+  response: single(session),
+  async handler({ body, req }) {
+    const made = await signUp({ name: body.name, email: body.email, password: body.password, phoneNumber: body.phone, notificationPreference: body.notificationPreference, newsOptIn: body.newsOptIn }, requestInfo(req));
+    return { data: { status: 'signed_in' as const, token: made.token, user: { id: made.id, name: made.name, email: made.email, role: made.role }, newsPromptPending: false, noticePromptPending: false as const } };
+  },
+});
+
+export const login = defineRoute({
+  method: 'post',
+  path: '/auth/login',
+  tag: 'Accounts',
+  summary: 'Log in',
+  description: [
+    'With an email address or phone number. Five wrong passwords lock the account for five minutes (`RATE_LIMITED`).',
+    'With two-factor authentication (always for supervisors and admins), the answer is `code_required`: a code was sent by email or WhatsApp — finish with `POST /auth/login/code`.',
+  ].join('\n\n'),
+  access: 'public',
+  middleware: [auth.loginLimiter],
+  body: z.object({
+    identifier: z.string().trim().min(1).max(200).describe('Email address or phone number'),
+    password: z.string().min(1).max(200),
+    deviceToken: z.string().max(500).optional().describe('From an earlier login with rememberDevice'),
+  }),
+  response: single(z.discriminatedUnion('status', [
+    session,
+    z.object({
+      status: z.literal('code_required'),
+      challengeId: z.string(),
+      method: z.enum(['email', 'whatsapp']),
+      destination: z.string().nullable().describe('Where the code went, partly hidden'),
+      enrolling: z.boolean().describe('true = this turns two-factor on (required for the role)'),
+    }),
+  ])),
+  async handler({ body, req }) {
+    const result = await logIn(body, requestInfo(req));
+    if (result.status === 'signed_in') return { data: toSession(result.session) };
+    return { data: { status: 'code_required' as const, challengeId: result.challenge.challengeId, method: result.challenge.method as 'email' | 'whatsapp', destination: result.challenge.destination ?? null, enrolling: result.enrolling } };
+  },
+});
+
+export const loginCode = defineRoute({
+  method: 'post',
+  path: '/auth/login/code',
+  tag: 'Accounts',
+  summary: 'Finish logging in with the code',
+  access: 'public',
+  middleware: [auth.loginLimiter],
+  body: z.object({
+    challengeId: z.string().min(1).max(100),
+    code: z.string().trim().min(4).max(12),
+    rememberDevice: z.boolean().optional().describe('Skip the code on this device next time (30 days)'),
+  }),
+  response: single(session),
+  async handler({ body, req }) {
+    return { data: toSession(await verifyLoginCode(body, requestInfo(req))) };
+  },
+});

backend/src/v2/resources/checkin.ts

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+import type { Request } from 'express';
+import { defineRoute } from '../route';
+import { ApiError } from '../errors';
+import { single } from '../paging';
+import { id } from '../schemas';
+import { previewScan, scanTicket, type ScanTicket } from '../../services/checkin';
+
+const OUTCOMES = ['checked_in', 'already_used', 'consent_required', 'wrong_event', 'wrong_section', 'section_not_found', 'no_session', 'locked', 'transferred'] as const;
+
+const qrParams = z.object({ qrCode: z.string().min(1).max(200).describe('The code in the ticket\'s QR') });
+
+/**
+ * Campus-scoped staff may only check in tickets for their campuses' events (and church-wide
+ * ones) — the same rule as v1's scopeEvent({ resolve: 'ticketQr', nameCampus: true }).
+ */
+async function assertTicketCampus(req: Request, qrCode: string) {
+  const cs = require('../../utils/campusScope') as {
+    scopeFor(req: unknown): Promise<object | null>;
+    eventOf(resolve: string, value: string): Promise<{ campusId: string | null; campusName?: string | null } | null>;
+    canView(scope: object, campusId: string | null): boolean;
+  };
+  const scope = await cs.scopeFor(req);
+  if (!scope) return;
+  const ev = await cs.eventOf('ticketQr', qrCode);
+  if (ev && !cs.canView(scope, ev.campusId)) throw new ApiError('FORBIDDEN', `This ticket is for an event at ${ev.campusName || 'another campus'}.`);
+}
+
+const ticketInfo = z.object({
+  id,
+  eventId: id,
+  eventTitle: z.string().nullable(),
+  ticketName: z.string().nullable().describe('The ticket option, e.g. "Adult"'),
+  quantity: z.number().int().describe('People on this ticket'),
+});
+const toTicketInfo = (t: ScanTicket) => ({ id: t.id, eventId: t.eventId, eventTitle: t.event.title ?? null, ticketName: t.registrationOption.eventOption.name ?? null, quantity: t.quantity });
+
+const sessionRef = z.object({ id, label: z.string() });
+
+export const preview = defineRoute({
+  method: 'get',
+  path: '/checkin/:qrCode',
+  tag: 'Check-in',
+  summary: 'Look a ticket up before checking it in',
+  description: 'Who it is for, how many are left to check in (for today\'s session on multi-day events, or `sessionId`), and parental consent. Nothing is changed.',
+  access: 'staff',
+  campusScope: 'event:ticketQr:view (assertTicketCampus)',
+  params: qrParams,
+  query: z.object({ sessionId: id.optional().describe('Multi-day events: the session (default: today\'s)') }),
+  response: single(z.object({
+    outcome: z.enum(['found', 'transferred']),
+    message: z.string().nullable().describe('For a transferred ticket: who has it now'),
+    ticket: z.object({
+      id,
+      eventId: id,
+      eventTitle: z.string().nullable(),
+      ticketOptionId: id.nullable().describe('For section checks'),
+      ticketName: z.string().nullable(),
+      variant: z.string().nullable(),
+      attendee: z.string().nullable().describe('The attendee named on it, if any'),
+      bookedBy: z.string().nullable().describe('Who registered'),
+      quantity: z.number().int(),
+      remaining: z.number().int().describe('Still to check in (this session, on multi-day events)'),
+      session: sessionRef.nullable(),
+      sessionError: z.string().nullable().describe('Why no session is open for check-in now'),
+      consentStatus: z.string().describe('not_required, given, pending, declined or missing'),
+    }).nullable(),
+  })),
+  async handler({ params, query, req }) {
+    await assertTicketCampus(req, params.qrCode);
+    const result = await previewScan(params.qrCode, { sessionId: query.sessionId ?? null });
+    if (result.outcome === 'transferred') return { data: { outcome: 'transferred' as const, message: result.message, ticket: null } };
+    const t = result.ticket;
+    return {
+      data: {
+        outcome: 'found' as const,
+        message: null,
+        ticket: {
+          id: t.id, eventId: t.eventId, eventTitle: t.event.title ?? null, ticketName: t.registrationOption.eventOption.name ?? null,
+          ticketOptionId: t.registrationOption.eventOption.id ?? null, variant: t.registrationOption.variant?.name ?? null,
+          attendee: t.attendee?.name ?? null, bookedBy: t.user.name ?? null, quantity: t.quantity,
+          remaining: t.remaining, session: t.session, sessionError: t.sessionError, consentStatus: t.consentStatus,
+        },
+      },
+    };
+  },
+});
+
+export const scan = defineRoute({
+  method: 'post',
+  path: '/checkin/:qrCode',
+  tag: 'Check-in',
+  summary: 'Check a ticket in',
+  description: [
+    'Checks in everyone left on the ticket, or `people`. Every normal result is a 200 with an `outcome`:',
+    '`checked_in`, `already_used`, `consent_required` (a supervisor can resend with `overrideConsent`, which is logged), `wrong_event`, `wrong_section`, `section_not_found`, `no_session` (multi-day: nothing open now), `locked` (offline-locked to another device) or `transferred` (handed on; `message` says to whom).',
+    'An unknown code is `NOT_FOUND`.',
+  ].join('\n\n'),
+  access: 'staff',
+  campusScope: 'event:ticketQr:view (assertTicketCampus)',
+  params: qrParams,
+  body: z.object({
+    eventId: id.optional().describe('Refuse tickets for any other event'),
+    sectionId: id.optional().describe('Only tickets valid for this section'),
+    sessionId: id.optional().describe('Multi-day events: the session (default: today\'s)'),
+    people: z.number().int().min(1).max(10000).optional().describe('How many to check in (default: everyone left)'),
+    overrideConsent: z.boolean().optional(),
+    deviceId: z.string().max(200).optional().describe('This scanner, so its own offline lock doesn\'t block it'),
+  }),
+  response: single(z.object({
+    outcome: z.enum(OUTCOMES),
+    message: z.string(),
+    ticket: ticketInfo.nullable(),
+    checkedIn: z.number().int().describe('People checked in by this request (0 unless checked_in)'),
+    remaining: z.number().int().nullable().describe('Still to check in afterwards'),
+    session: sessionRef.nullable(),
+    consentStatus: z.string().nullable(),
+    canOverride: z.boolean().describe('consent_required: whether you may override'),
+  })),
+  async handler({ params, body, user, req }) {
+    await assertTicketCampus(req, params.qrCode);
+    const { getClientIp } = require('../../utils/requestUtils') as { getClientIp(req: unknown): string };
+    const r = await scanTicket(params.qrCode, user!, {
+      eventId: body.eventId, sectionId: body.sectionId, sessionId: body.sessionId, deviceId: body.deviceId,
+      qty: body.people ?? null, overrideConsent: body.overrideConsent,
+    }, getClientIp(req));
+    const base = { outcome: r.outcome, message: r.message, ticket: 'ticket' in r ? toTicketInfo(r.ticket) : null, checkedIn: 0, remaining: null as number | null, session: null as { id: string; label: string } | null, consentStatus: null as string | null, canOverride: false };
+    if (r.outcome === 'checked_in') return { data: { ...base, checkedIn: r.qtyRedeemed, remaining: r.remaining, session: r.session } };
+    if (r.outcome === 'already_used') return { data: { ...base, remaining: 0 } };
+    if (r.outcome === 'consent_required') return { data: { ...base, consentStatus: r.consentStatus, canOverride: r.canOverride } };
+    return { data: base };
+  },
+});

backend/src/v2/resources/eventDetails.ts

@@ -0,0 +1,282 @@
+import { z } from 'zod';
+import type { Request } from 'express';
+import { defineRoute, fileResponse, type ApiUser } from '../route';
+import { ApiError } from '../errors';
+import { single } from '../paging';
+import { absoluteUrl, id, idParams, isoDate } from '../schemas';
+import * as details from '../../services/eventDetails';
+import { managedEvent } from './eventsManage';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- stored records are passed through */
+const campusScope = require('../../utils/campusScope') as {
+  scopeFor(req: unknown): Promise<object | null>;
+  scopeEvent(opts?: { need?: 'view' | 'manage'; resolve?: string; from?: (req: any) => unknown }): any;
+};
+// The same multer step as v1 (field "file"; PDFs, Office files, text, CSV, ZIP; 20 MB).
+const { receiveAttachment } = require('../../controllers/eventController') as { receiveAttachment: any };
+
+const urlOf = (req: Request) => (u: string | null | undefined) => absoluteUrl(req, u);
+const plain = <T>(v: T): any => JSON.parse(JSON.stringify(v));
+const viewerOf = async (req: Request, user: ApiUser | null) => ({ staff: !!user && ['admin', 'supervisor', 'staff'].includes(user.role), scope: await campusScope.scopeFor(req) });
+
+// ─── The event in full, calendar file, short link ──────────────────────────────
+
+export const full = defineRoute({
+  method: 'get',
+  path: '/events/:id/full',
+  tag: 'Events',
+  summary: 'One event in full',
+  description: [
+    'What the registration page and the set-up screens need: ticket options with what\'s left (per variant, and per session for "pick sessions" tickets), early-bird tiers, sessions with bookings, the attendee form, attachments, bundle deals on sale and the next event in its series.',
+    'Staff (of a campus they work with) also get inactive and not-yet-live events, who created it, who gets its emails, and the kids/volunteer tickets. Everyone else gets NOT_FOUND for events that aren\'t public.',
+  ].join('\n\n'),
+  access: 'optional',
+  params: idParams,
+  response: single(managedEvent.extend({
+    form: z.looseObject({ id, isRequired: z.boolean(), fields: z.array(z.looseObject({ id, type: z.string(), label: z.string() })) }).nullable(),
+    attachments: z.array(z.looseObject({ id, originalName: z.string(), url: z.string().nullable() })),
+  })),
+  async handler({ params, user, req }) {
+    return { data: plain(await details.getEventDetail(params.id, await viewerOf(req, user), urlOf(req))) };
+  },
+});
+
+export const calendar = defineRoute({
+  method: 'get',
+  path: '/events/:id/calendar.ics',
+  tag: 'Events',
+  summary: 'The event as a calendar file',
+  description: 'An .ics file (each session for a multi-day event). Same visibility as the event.',
+  access: 'optional',
+  file: { contentType: 'text/calendar' },
+  params: idParams,
+  response: fileResponse,
+  async handler({ params, user, req }) {
+    const { filename, ics } = await details.eventCalendar(params.id, await viewerOf(req, user));
+    return { data: { contentType: 'text/calendar; charset=utf-8', filename, body: ics } };
+  },
+});
+
+export const byAlias = defineRoute({
+  method: 'get',
+  path: '/events/by-alias/:alias',
+  tag: 'Events',
+  summary: 'An event by its short link',
+  description: 'The part after the site address (`/camp2026`), any letter case. Active events only.',
+  access: 'public',
+  params: z.object({ alias: z.string().min(1).max(100).describe('The short link, e.g. camp2026') }),
+  response: single(z.object({
+    id, title: z.string(), description: z.string().nullable(), startDate: isoDate, endDate: isoDate, registrationDeadline: isoDate.nullable(),
+    goLiveAt: isoDate.nullable(), price: z.number(), picture: z.string().nullable(), redirectUrl: z.string().nullable(),
+    isLive: z.boolean().describe('Not over yet'),
+  })),
+  async handler({ params, req }) {
+    const ev = plain(await details.eventByAlias(params.alias));
+    return { data: { ...ev, picture: absoluteUrl(req, ev.picture) } };
+  },
+});
+
+// ─── Ticket options and variants ─────────────────────────────────────────────
+
+const variant = z.looseObject({ id, name: z.string(), price: z.number().nullable(), stockLimit: z.number().int(), staffPrice: z.number().nullable(), order: z.number().int() });
+const tier = z.looseObject({ id, deadline: isoDate, price: z.number(), stockLimit: z.number().int(), variantId: id.nullable() });
+const ticketOption = z.looseObject({
+  id, eventId: id, name: z.string(), price: z.number(), isMainTicket: z.boolean(), stockLimit: z.number().int(), staffPrice: z.number().nullable(),
+  sessionMode: z.enum(['all', 'pick']), earlyBirdTiers: z.array(tier).optional(), variants: z.array(variant).optional(),
+});
+const money = z.union([z.number(), z.string().max(20)]);
+const optionBody = z.object({
+  name: z.string().trim().min(1).max(120),
+  price: money,
+  isMainTicket: z.boolean().optional(),
+  stockLimit: z.union([z.number().int().min(0), z.string().max(10)]).optional().describe('0 = no limit'),
+  staffPrice: money.nullable().optional().describe('What staff pay (empty = the normal price)'),
+  sessionMode: z.enum(['all', 'pick']).optional().describe('"pick" = buyers choose sessions (multi-day events)'),
+});
+const variantBody = z.object({
+  name: z.string().trim().min(1).max(120),
+  price: money.nullable().optional().describe('Empty = the option\'s price'),
+  stockLimit: z.union([z.number().int().min(0), z.string().max(10)]).optional(),
+  staffPrice: money.nullable().optional(),
+  order: z.union([z.number().int(), z.string().max(10)]).optional(),
+});
+
+export const createOption = defineRoute({
+  method: 'post',
+  path: '/events/:id/ticket-options',
+  tag: 'Events (staff)',
+  summary: 'Add a ticket option',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(manage)',
+  middleware: [campusScope.scopeEvent({ need: 'manage' })],
+  status: 201,
+  params: idParams,
+  body: optionBody,
+  response: single(ticketOption),
+  async handler({ params, body }) {
+    return { data: plain(await details.createOption(params.id, body)) };
+  },
+});
+
+export const updateOption = defineRoute({
+  method: 'patch',
+  path: '/ticket-options/:id',
+  tag: 'Events (staff)',
+  summary: 'Change a ticket option',
+  description: 'Only what\'s sent changes. `earlyBirdTiers` and `variants`, when sent, are the full lists: kept by id, added without one, and ones left out removed when nothing was bought under them.',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(eventOption, manage)',
+  middleware: [campusScope.scopeEvent({ resolve: 'eventOption', need: 'manage' })],
+  params: idParams,
+  body: optionBody.partial().extend({
+    earlyBirdTiers: z.array(z.looseObject({ id: id.optional(), deadline: z.string().max(40), price: money, stockLimit: z.union([z.number(), z.string()]).optional(), variantId: id.nullable().optional() })).max(50).optional(),
+    variants: z.array(variantBody.extend({ id: id.optional() })).max(100).optional(),
+  }),
+  response: single(ticketOption),
+  async handler({ params, body }) {
+    return { data: plain(await details.updateOption(params.id, body)) };
+  },
+});
+
+export const deleteOption = defineRoute({
+  method: 'delete',
+  path: '/ticket-options/:id',
+  tag: 'Events (staff)',
+  summary: 'Remove a ticket option',
+  description: 'Admins only. Not one anybody has bought, and never the event\'s only main ticket.',
+  access: 'admin',
+  params: idParams,
+  response: single(z.object({ id, deleted: z.literal(true) })),
+  async handler({ params }) {
+    await details.deleteOption(params.id);
+    return { data: { id: params.id, deleted: true as const } };
+  },
+});
+
+export const createVariant = defineRoute({
+  method: 'post',
+  path: '/ticket-options/:id/variants',
+  tag: 'Events (staff)',
+  summary: 'Add a variant (e.g. a T-shirt size)',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(eventOption, manage)',
+  middleware: [campusScope.scopeEvent({ resolve: 'eventOption', need: 'manage' })],
+  status: 201,
+  params: idParams,
+  body: variantBody,
+  response: single(variant),
+  async handler({ params, body }) {
+    return { data: plain(await details.createVariant(params.id, body)) };
+  },
+});
+
+export const updateVariant = defineRoute({
+  method: 'patch',
+  path: '/variants/:id',
+  tag: 'Events (staff)',
+  summary: 'Change a variant',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(optionVariant, manage)',
+  middleware: [campusScope.scopeEvent({ resolve: 'optionVariant', need: 'manage' })],
+  params: idParams,
+  body: variantBody.partial(),
+  response: single(variant),
+  async handler({ params, body }) {
+    return { data: plain(await details.updateVariant(params.id, body)) };
+  },
+});
+
+export const deleteVariant = defineRoute({
+  method: 'delete',
+  path: '/variants/:id',
+  tag: 'Events (staff)',
+  summary: 'Remove a variant',
+  description: 'Admins only, and not one anybody has bought.',
+  access: 'admin',
+  params: idParams,
+  response: single(z.object({ id, deleted: z.literal(true) })),
+  async handler({ params }) {
+    await details.deleteVariant(params.id);
+    return { data: { id: params.id, deleted: true as const } };
+  },
+});
+
+// ─── Attachments ─────────────────────────────────────────────────────────────
+
+const attachment = z.object({ id, eventId: id, originalName: z.string(), filename: z.string(), mimeType: z.string(), size: z.number().int(), url: z.string().nullable(), createdAt: isoDate });
+
+export const listAttachments = defineRoute({
+  method: 'get',
+  path: '/events/:id/attachments',
+  tag: 'Events',
+  summary: 'An event\'s attachments',
+  description: 'Files for attendees (programmes, packing lists…), newest first.',
+  access: 'public',
+  params: idParams,
+  response: z.object({ data: z.array(attachment) }),
+  async handler({ params, req }) {
+    return { data: plain(await details.listAttachments(params.id, urlOf(req))) };
+  },
+});
+
+export const uploadAttachment = defineRoute({
+  method: 'post',
+  path: '/events/:id/attachments',
+  tag: 'Events (staff)',
+  summary: 'Attach a file to an event',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(manage)',
+  middleware: [campusScope.scopeEvent({ need: 'manage' }), receiveAttachment],
+  upload: { field: 'file', description: 'PDF, Word, Excel, PowerPoint, text, CSV or ZIP, up to 20 MB' },
+  status: 201,
+  params: idParams,
+  response: single(attachment),
+  async handler({ params, req }) {
+    const r = req as Request & { multerError?: Error; file?: { originalname: string; filename: string; mimetype: string; size: number } };
+    if (r.multerError) throw new ApiError('VALIDATION_FAILED', r.multerError.message, { file: r.multerError.message });
+    if (!r.file) throw new ApiError('VALIDATION_FAILED', 'No file uploaded', { file: 'Choose a file' });
+    return { data: plain(await details.recordAttachment(params.id, r.file, urlOf(req))) };
+  },
+});
+
+export const deleteAttachment = defineRoute({
+  method: 'delete',
+  path: '/events/:id/attachments/:attachmentId',
+  tag: 'Events (staff)',
+  summary: 'Remove an attachment',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(manage)',
+  middleware: [campusScope.scopeEvent({ need: 'manage' })],
+  params: z.object({ id, attachmentId: id }),
+  response: single(z.object({ id, deleted: z.literal(true) })),
+  async handler({ params }) {
+    await details.deleteAttachment(params.id, params.attachmentId);
+    return { data: { id: params.attachmentId, deleted: true as const } };
+  },
+});
+
+export const attachmentsStatus = defineRoute({
+  method: 'get',
+  path: '/attachments/status',
+  tag: 'Admin',
+  summary: 'Attachments diagnostics',
+  access: 'admin',
+  response: single(z.looseObject({ databaseTableQueryable: z.boolean(), probeError: z.string().nullable() })),
+  async handler() {
+    return { data: plain(await details.attachmentsStatus()) };
+  },
+});
+
+export const attachmentsSync = defineRoute({
+  method: 'post',
+  path: '/attachments/sync',
+  tag: 'Admin',
+  summary: 'Import attachments from old manifests',
+  description: 'Attachments recorded in JSON files on disk by very old versions go into the database. `dryRun` only reports; `remove` deletes each manifest once imported.',
+  access: 'admin',
+  body: z.object({ dryRun: z.boolean().default(false), remove: z.boolean().default(false) }),
+  response: single(z.looseObject({ dryRun: z.boolean(), remove: z.boolean() })),
+  async handler({ body }) {
+    return { data: plain(await details.syncAttachmentManifests(body)) };
+  },
+});

backend/src/v2/resources/events.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+import { defineRoute } from '../route';
+import { notFound } from '../errors';
+import { pageQuery, paged, single, skipTake, pageOf } from '../paging';
+import { absoluteUrl, campusRef, id, idParams, iso, isoDate, seriesRef } from '../schemas';
+import { prisma, campusesEnabled, campusWhere, resolveCampusFilter, publicEventWhere, publicOptions, getEffectiveUnitPrice } from '../legacy';
+
+const eventSummary = z.object({
+  id,
+  title: z.string(),
+  startDate: isoDate,
+  endDate: isoDate,
+  location: z.string().nullable(),
+  price: z.number().describe('The headline price in rand (0 = free)'),
+  pictureUrl: z.string().nullable(),
+  requiresRegistration: z.boolean(),
+  scheduleType: z.enum(['single', 'sessions']),
+  campus: campusRef.nullable().describe('null = for all campuses (or campuses are off)'),
+  series: seriesRef.nullable(),
+});
+
+const ticketOption = z.object({
+  id,
+  name: z.string(),
+  price: z.number().describe('The normal price in rand'),
+  currentPrice: z.number().describe('What it costs now (an early-bird price while one runs)'),
+  isMainTicket: z.boolean(),
+  sessionMode: z.enum(['all', 'pick']).describe('"pick" = the buyer chooses sessions'),
+});
+
+const session = z.object({
+  id,
+  label: z.string().nullable(),
+  startsAt: isoDate,
+  endsAt: isoDate,
+  location: z.string().nullable(),
+  cancelled: z.boolean(),
+});
+
+const eventDetail = eventSummary.extend({
+  description: z.string().nullable(),
+  registrationDeadline: isoDate.nullable(),
+  ticketOptions: z.array(ticketOption),
+  sessions: z.array(session).describe('Multi-day events only; empty otherwise'),
+});
+
+const SUMMARY_SELECT = {
+  id: true, title: true, startDate: true, endDate: true, location: true, price: true, picture: true,
+  requiresRegistration: true, scheduleType: true,
+  campus: { select: { id: true, name: true, slug: true } },
+  series: { select: { id: true, name: true, slug: true } },
+} as const;
+
+type SummaryRow = {
+  id: string; title: string; startDate: Date; endDate: Date; location: string | null; price: number; picture: string | null;
+  requiresRegistration: boolean; scheduleType: 'single' | 'sessions';
+  campus: { id: string; name: string; slug: string } | null; series: { id: string; name: string; slug: string } | null;
+};
+
+const toSummary = (req: Parameters<typeof absoluteUrl>[0], e: SummaryRow): z.input<typeof eventSummary> => ({
+  id: e.id, title: e.title, startDate: iso(e.startDate), endDate: iso(e.endDate), location: e.location ?? null,
+  price: e.price, pictureUrl: absoluteUrl(req, e.picture), requiresRegistration: e.requiresRegistration,
+  scheduleType: e.scheduleType, campus: e.campus ?? null, series: e.series ?? null,
+});
+
+export const listEvents = defineRoute({
+  method: 'get',
+  path: '/events',
+  tag: 'Events',
+  summary: 'Upcoming public events',
+  description: 'Events anyone can see (active, not hidden, live) that have not ended, soonest first.',
+  access: 'public',
+  query: pageQuery.extend({
+    q: z.string().trim().max(100).optional().describe('Search the title'),
+    campus: z.string().max(64).optional().describe("A campus id or slug (its events plus church-wide ones), or 'all' for church-wide events only"),
+    series: z.string().max(120).optional().describe('A series slug'),
+  }),
+  response: paged(eventSummary),
+  async handler({ query, req }) {
+    const now = new Date();
+    const enabled = await campusesEnabled();
+    const and: object[] = [publicEventWhere(now), { endDate: { gte: now } }];
+    if (query.campus) and.push(campusWhere(await resolveCampusFilter(query.campus), { enabled, withAllCampuses: true }));
+    if (query.series) and.push({ series: { slug: query.series } });
+    if (query.q) and.push({ title: { contains: query.q, mode: 'insensitive' } });
+    const where = { AND: and };
+    const [rows, total] = await Promise.all([
+      prisma.event.findMany({ where, select: SUMMARY_SELECT, orderBy: [{ startDate: 'asc' }, { id: 'asc' }], ...skipTake(query) }),
+      prisma.event.count({ where }),
+    ]);
+    return pageOf((rows as SummaryRow[]).map(e => toSummary(req, e)), total, query);
+  },
+});
+
+export const getEvent = defineRoute({
+  method: 'get',
+  path: '/events/:id',
+  tag: 'Events',
+  summary: 'One public event',
+  description: 'With its ticket options (internal kids check-in and volunteer tickets left out) and sessions. Hidden events can be fetched by id (they are unlisted, not private).',
+  access: 'public',
+  params: idParams,
+  response: single(eventDetail),
+  async handler({ params, req }) {
+    const now = new Date();
+    const { isHidden: _hiddenOk, ...visible } = publicEventWhere(now);
+    const e = await prisma.event.findFirst({
+      where: { id: params.id, ...visible },
+      select: {
+        ...SUMMARY_SELECT, description: true, registrationDeadline: true, kidsOptionId: true, volunteerOptionId: true,
+        eventOptions: { include: { earlyBirdTiers: true }, orderBy: [{ isMainTicket: 'desc' }, { name: 'asc' }] },
+        sessions: { orderBy: { startsAt: 'asc' } },
+      },
+    });
+    if (!e) throw notFound('That event');
+    const options = publicOptions(e);
+    return {
+      data: {
+        ...toSummary(req, e as unknown as SummaryRow),
+        description: e.description ?? null,
+        registrationDeadline: iso(e.registrationDeadline),
+        ticketOptions: options.map(o => ({
+          id: o.id, name: o.name, price: o.price, currentPrice: getEffectiveUnitPrice(o, null, now),
+          isMainTicket: o.isMainTicket, sessionMode: o.sessionMode,
+        })),
+        sessions: e.sessions.map(s => ({ id: s.id, label: s.label, startsAt: iso(s.startsAt), endsAt: iso(s.endsAt), location: s.location, cancelled: !!s.cancelledAt })),
+      },
+    };
+  },
+});

backend/src/v2/resources/eventsManage.ts

@@ -0,0 +1,190 @@
+import { z } from 'zod';
+import type { Request } from 'express';
+import { defineRoute, type ApiUser } from '../route';
+import { single } from '../paging';
+import { absoluteUrl, id, idParams, isoDate } from '../schemas';
+import {
+  createEvent, updateEvent, deactivateEvent, listManagedEvents, getNotifyRecipients, setNotifyRecipients, copySetupFrom,
+} from '../../services/events';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- event records are passed through as stored */
+const campusScope = require('../../utils/campusScope') as {
+  scopeFor(req: unknown): Promise<object | null>;
+  scopeEvent(opts?: { need?: 'view' | 'manage'; resolve?: string; from?: (req: any) => unknown }): any;
+  scopeBody(targets: [string, string][], opts?: object): any;
+};
+
+/**
+ * Staff and supervisor views of events (1.51.7). Event records are large (ticket options with
+ * tiers and variants, the attendee form, sessions…) and grow with features, so the schema types
+ * the core fields and lets the rest through as stored (`looseObject`); dates come back as ISO
+ * strings. Registered before resources/events.ts so /events/manage isn't read as an event id.
+ */
+const option = z.looseObject({ id, name: z.string(), price: z.number(), isMainTicket: z.boolean(), stockLimit: z.number().int() });
+const session = z.looseObject({ id, label: z.string().nullable(), startsAt: isoDate, endsAt: isoDate, cancelled: z.boolean() });
+export const managedEvent = z.looseObject({
+  id,
+  title: z.string(),
+  description: z.string().nullable(),
+  startDate: isoDate,
+  endDate: isoDate,
+  isActive: z.boolean(),
+  isHidden: z.boolean(),
+  requiresRegistration: z.boolean(),
+  scheduleType: z.enum(['single', 'sessions']),
+  attendanceMode: z.enum(['whole', 'pick']),
+  cashupStatus: z.enum(['open', 'closed']),
+  campusId: id.nullable(),
+  seriesId: id.nullable(),
+  picture: z.string().nullable(),
+  eventOptions: z.array(option).optional(),
+  sessions: z.array(session).optional(),
+});
+
+/** A stored record as JSON (dates → ISO strings), with the picture as an absolute URL. */
+const toJson = (req: Request, ev: any) => {
+  const plain = JSON.parse(JSON.stringify(ev));
+  if ('picture' in plain) plain.picture = absoluteUrl(req, plain.picture);
+  return plain;
+};
+
+const ctxOf = async (req: Request) => {
+  const { getClientIp } = require('../../utils/requestUtils') as { getClientIp(req: unknown): string };
+  return { scope: await campusScope.scopeFor(req), ip: getClientIp(req) };
+};
+const actorOf = (user: ApiUser | null) => ({ id: user!.id, role: user!.role });
+
+// The event wizard's fields. Only these are named here; the rest of the wizard's fields (consent,
+// waitlist, sponsorship, sessions, late joining, certificates, form…) pass through as sent.
+const eventBody = z.looseObject({
+  title: z.string().trim().min(1).max(200).optional(),
+  description: z.string().max(20000).nullable().optional(),
+  startDate: z.string().max(40).optional(),
+  endDate: z.string().max(40).optional(),
+  price: z.union([z.number(), z.string().max(20)]).optional(),
+  campusId: id.nullable().optional(),
+  seriesId: id.nullable().optional(),
+  scheduleType: z.enum(['single', 'sessions']).optional(),
+  sessions: z.array(z.looseObject({})).max(200).optional(),
+});
+
+export const listManaged = defineRoute({
+  method: 'get',
+  path: '/events/manage',
+  tag: 'Events (staff)',
+  summary: 'Every event staff can see',
+  description: 'Hidden ones too. Upcoming by default; `past`, `inactive` and `closed` (cashed-up) widen it. Campus-scoped staff see their campuses\' events and church-wide ones. Not paged — it\'s what the event pickers search.',
+  access: 'staff',
+  campusScope: 'scopeList (in listManagedEvents)',
+  query: z.object({
+    past: z.enum(['true', 'false']).default('false').transform(v => v === 'true').describe('Include events that have ended'),
+    inactive: z.enum(['true', 'false']).default('false').transform(v => v === 'true').describe('Include deactivated events'),
+    closed: z.enum(['true', 'false']).default('true').transform(v => v === 'true').describe('Include cashed-up events (default true)'),
+    campus: z.string().max(64).optional().describe("A campus id or slug, or 'all' for church-wide events only"),
+  }),
+  response: z.object({ data: z.array(managedEvent) }),
+  async handler({ query, req }) {
+    const events = await listManagedEvents({ includePast: query.past, includeInactive: query.inactive, excludeClosed: !query.closed, campus: query.campus }, await ctxOf(req));
+    return { data: events.map(ev => toJson(req, ev)) };
+  },
+});
+
+export const create = defineRoute({
+  method: 'post',
+  path: '/events',
+  tag: 'Events (staff)',
+  summary: 'Create an event',
+  description: 'Gets a "Main Ticket" at the event price (unless registration is off). A campus-scoped supervisor must choose one of their campuses.',
+  access: 'supervisor',
+  campusScope: 'campus checked in createEvent (assertCampusAllowed)',
+  status: 201,
+  body: eventBody.extend({ title: z.string().trim().min(1).max(200), startDate: z.string().max(40), endDate: z.string().max(40) }),
+  response: single(managedEvent),
+  async handler({ body, user, req }) {
+    return { data: toJson(req, await createEvent(body, actorOf(user), await ctxOf(req))) };
+  },
+});
+
+export const update = defineRoute({
+  method: 'patch',
+  path: '/events/:id',
+  tag: 'Events (staff)',
+  summary: 'Change an event',
+  description: 'Only the fields sent change. Sessions save with the event (a refused schedule change saves nothing). A cashed-up event can\'t change until an admin reopens it. The answer includes `sessionChanges` (added, moved, cancelled… counts) when sessions were sent.',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(manage)',
+  middleware: [campusScope.scopeEvent({ need: 'manage' })],
+  params: idParams,
+  body: eventBody,
+  response: single(managedEvent.extend({ sessionChanges: z.record(z.string(), z.number()).nullable() })),
+  async handler({ params, body, user, req }) {
+    return { data: toJson(req, await updateEvent(params.id, body, actorOf(user), await ctxOf(req))) };
+  },
+});
+
+export const remove = defineRoute({
+  method: 'delete',
+  path: '/events/:id',
+  tag: 'Events (staff)',
+  summary: 'Deactivate an event',
+  description: 'Admins only. The event is deactivated, not deleted: registrations, payments and tickets stay.',
+  access: 'admin',
+  params: idParams,
+  response: single(z.object({ id, isActive: z.literal(false) })),
+  async handler({ params, user, req }) {
+    const ev = await deactivateEvent(params.id, actorOf(user), await ctxOf(req));
+    return { data: { id: ev.id, isActive: false as const } };
+  },
+});
+
+export const copyFrom = defineRoute({
+  method: 'post',
+  path: '/events/:id/copy-from',
+  tag: 'Events (staff)',
+  summary: 'Copy set-up from another event',
+  description: 'Allocation groups, and planned costs for admins — used right after copying an event.',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(manage) + scopeBody(fromEventId)',
+  middleware: [campusScope.scopeEvent({ need: 'manage' }), campusScope.scopeBody([['fromEventId', 'event']])],
+  params: idParams,
+  body: z.object({ fromEventId: id }),
+  response: single(z.looseObject({})),
+  async handler({ params, body, user }) {
+    return { data: JSON.parse(JSON.stringify(await copySetupFrom(params.id, body.fromEventId, actorOf(user)) ?? {})) };
+  },
+});
+
+const recipient = z.object({ id, name: z.string(), email: z.string(), role: z.enum(['admin', 'supervisor', 'staff', 'user']) });
+
+export const listRecipients = defineRoute({
+  method: 'get',
+  path: '/events/:id/notify-recipients',
+  tag: 'Events (staff)',
+  summary: 'Who gets this event\'s emails',
+  description: 'Registration, payment and daily-summary emails.',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(view)',
+  middleware: [campusScope.scopeEvent()],
+  params: idParams,
+  response: z.object({ data: z.array(recipient) }),
+  async handler({ params }) {
+    return { data: await getNotifyRecipients(params.id) };
+  },
+});
+
+export const setRecipients = defineRoute({
+  method: 'put',
+  path: '/events/:id/notify-recipients',
+  tag: 'Events (staff)',
+  summary: 'Set who gets this event\'s emails',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(manage)',
+  middleware: [campusScope.scopeEvent({ need: 'manage' })],
+  params: idParams,
+  body: z.object({ userIds: z.array(id).max(200) }),
+  response: z.object({ data: z.array(recipient) }),
+  async handler({ params, body }) {
+    return { data: await setNotifyRecipients(params.id, body.userIds) };
+  },
+});
+

backend/src/v2/resources/me.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import { defineRoute } from '../route';
+import { ApiError } from '../errors';
+import { pageQuery, paged, single, skipTake, pageOf } from '../paging';
+import { id, iso, isoDate } from '../schemas';
+import { prisma } from '../legacy';
+import { registrationSummary, SUMMARY_INCLUDE, toSummary } from './registrations';
+import { updateProfile } from '../../services/auth';
+
+const me = z.object({
+  id,
+  name: z.string(),
+  email: z.string(),
+  phone: z.string().nullable(),
+  role: z.enum(['admin', 'supervisor', 'staff', 'user']),
+  twoFactorEnabled: z.boolean(),
+  notificationPreference: z.enum(['email', 'whatsapp', 'both']),
+  homeCampusId: id.nullable(),
+  createdAt: isoDate,
+});
+
+type MeRow = { id: string; name: string; email: string; phoneNumber: string | null; role: 'admin' | 'supervisor' | 'staff' | 'user'; twoFactorEnabled: boolean | null; notificationPreference: 'email' | 'whatsapp' | 'both'; homeCampusId: string | null; createdAt: Date };
+const toMe = (u: MeRow): z.input<typeof me> => ({
+  id: u.id, name: u.name, email: u.email, phone: u.phoneNumber ?? null, role: u.role, twoFactorEnabled: !!u.twoFactorEnabled,
+  notificationPreference: u.notificationPreference, homeCampusId: u.homeCampusId ?? null, createdAt: iso(u.createdAt),
+});
+
+export const getMe = defineRoute({
+  method: 'get',
+  path: '/me',
+  tag: 'Me',
+  summary: 'The signed-in person',
+  access: 'user',
+  response: single(me),
+  async handler({ user }) {
+    const u = await prisma.user.findUnique({
+      where: { id: user!.id },
+      select: { id: true, name: true, email: true, phoneNumber: true, role: true, twoFactorEnabled: true, notificationPreference: true, homeCampusId: true, createdAt: true },
+    });
+    if (!u) throw new ApiError('UNAUTHENTICATED', 'User not found');
+    return { data: toMe(u) };
+  },
+});
+
+export const updateMe = defineRoute({
+  method: 'patch',
+  path: '/me',
+  tag: 'Me',
+  summary: 'Change my details',
+  description: 'Only what is sent changes. A new `password` needs `currentPassword`; it sends a security notice and stops other devices skipping the 2FA code. The answer has a fresh `token` (the old one keeps working).',
+  access: 'user',
+  body: z.object({
+    name: z.string().trim().min(1).max(200).optional(),
+    email: z.email().max(200).optional(),
+    phone: z.string().trim().max(40).nullable().optional().describe('null or empty removes it'),
+    notificationPreference: z.enum(['email', 'whatsapp', 'both']).optional(),
+    homeCampusId: id.nullable().optional().describe('While campuses are on'),
+    password: z.string().min(8).max(200).optional(),
+    currentPassword: z.string().max(200).optional(),
+  }),
+  response: single(me).extend({ token: z.string() }),
+  async handler({ body, user, req }) {
+    const { getClientIp } = require('../../utils/requestUtils') as { getClientIp(req: unknown): string };
+    const { user: u, token } = await updateProfile(user!.id, { ...body, phoneNumber: body.phone }, { ip: getClientIp(req), userAgent: req.headers['user-agent'] });
+    return { data: toMe(u), token };
+  },
+});
+
+export const listMyRegistrations = defineRoute({
+  method: 'get',
+  path: '/me/registrations',
+  tag: 'Me',
+  summary: 'My registrations',
+  description: 'Newest first. By default only ones for events that have not ended, and not cancelled; `past=true` lists everything.',
+  access: 'user',
+  query: pageQuery.extend({
+    past: z.enum(['true', 'false']).default('false').transform(v => v === 'true').describe('Include past and cancelled registrations'),
+  }),
+  response: paged(registrationSummary),
+  async handler({ query, user }) {
+    const now = new Date();
+    const where = query.past
+      ? { userId: user!.id }
+      : { userId: user!.id, status: { not: 'cancelled' as const }, event: { endDate: { gte: now } } };
+    const [rows, total] = await Promise.all([
+      prisma.registration.findMany({ where, include: SUMMARY_INCLUDE, orderBy: [{ createdAt: 'desc' }, { id: 'desc' }], ...skipTake(query) }),
+      prisma.registration.count({ where }),
+    ]);
+    return pageOf(rows.map(r => toSummary(r, now)), total, query);
+  },
+});

backend/src/v2/resources/registrations.ts

@@ -0,0 +1,187 @@
+import { z } from 'zod';
+import { defineRoute, type ApiUser } from '../route';
+import { ApiError, notFound } from '../errors';
+import { single } from '../paging';
+import { eventRef, id, idParams, iso, isoDate } from '../schemas';
+import { prisma, computeRegistrationTotalDue } from '../legacy';
+import { createRegistration, cancelRegistration } from '../../services/registrations';
+import { startRegistrationCheckout } from '../../services/payments';
+
+const STATUSES = ['pending', 'confirmed', 'partial_paid', 'paid', 'cancelled'] as const;
+
+/** A registration as v2 shows it to its owner. Also used by GET /me/registrations. */
+export const registrationSummary = z.object({
+  id,
+  status: z.enum(STATUSES),
+  createdAt: isoDate,
+  event: eventRef,
+  items: z.array(z.object({
+    ticket: z.string(),
+    variant: z.string().nullable(),
+    quantity: z.number().int(),
+    unitPrice: z.number(),
+  })),
+  totalDue: z.number().describe('In rand, after discounts'),
+  amountPaid: z.number().describe('In rand (refunds subtracted)'),
+  balance: z.number().describe('totalDue − amountPaid; 0 or less = nothing owing'),
+});
+
+const r2 = (n: number) => Math.round(n * 100) / 100;
+
+export const SUMMARY_INCLUDE = {
+  event: { select: { id: true, title: true, startDate: true, endDate: true } },
+  registrationOptions: { include: { eventOption: { include: { earlyBirdTiers: true } }, variant: { select: { name: true, price: true } }, tranches: true } },
+  payments: { select: { amount: true, createdAt: true } },
+} as const;
+
+type SummaryRow = {
+  id: string; status: (typeof STATUSES)[number]; createdAt: Date;
+  event: { id: string; title: string; startDate: Date; endDate: Date };
+  registrationOptions: { quantity: number; priceSnapshot: number | null; eventOption: { name: string; price: number } | null; variant: { name: string } | null }[];
+  payments: { amount: number }[];
+};
+
+export function toSummary(r: SummaryRow, now = new Date()): z.input<typeof registrationSummary> {
+  const totalDue = r2(computeRegistrationTotalDue(r, now));
+  const amountPaid = r2(r.payments.reduce((s, p) => s + p.amount, 0));
+  return {
+    id: r.id,
+    status: r.status,
+    createdAt: iso(r.createdAt),
+    event: { id: r.event.id, title: r.event.title, startDate: iso(r.event.startDate), endDate: iso(r.event.endDate) },
+    items: r.registrationOptions.map(o => ({ ticket: o.eventOption?.name ?? '', variant: o.variant?.name ?? null, quantity: o.quantity, unitPrice: o.priceSnapshot ?? o.eventOption?.price ?? 0 })),
+    totalDue,
+    amountPaid,
+    balance: r2(totalDue - amountPaid),
+  };
+}
+
+/** The owner's registration (admins may see anyone's); others get NOT_FOUND, not a hint it exists. */
+async function ownRegistration(registrationId: string, user: ApiUser) {
+  const r = await prisma.registration.findUnique({ where: { id: registrationId }, include: SUMMARY_INCLUDE });
+  if (!r || (r.userId !== user.id && user.role !== 'admin')) throw notFound('That registration');
+  return r;
+}
+
+const attendee = z.object({
+  eventOptionId: id,
+  variantId: id.nullish(),
+  name: z.string().trim().min(1).max(200),
+  email: z.string().trim().max(200).nullish(),
+  phone: z.string().trim().max(40).nullish(),
+  dateOfBirth: z.string().max(40).nullish().describe('YYYY-MM-DD (youth events)'),
+  gender: z.string().max(20).nullish(),
+  parentName: z.string().max(200).nullish(),
+  parentEmail: z.string().max(200).nullish(),
+  parentPhone: z.string().max(40).nullish(),
+});
+
+export const register = defineRoute({
+  method: 'post',
+  path: '/registrations',
+  tag: 'Registrations',
+  summary: 'Register for an event',
+  description: [
+    'Signed in, or as a guest for a free event that allows it (`guest` then required), or with a waitlist link (`waitlistToken`).',
+    'Registering again for the same event adds to the existing registration. When nothing is owed it is marked paid and tickets are issued; otherwise pay with `POST /registrations/{id}/checkout`.',
+    'A coupon that was valid when checked but used up a moment later is reported in `couponError`; the registration is still made.',
+  ].join('\n\n'),
+  access: 'optional',
+  status: 201,
+  body: z.object({
+    eventId: id,
+    options: z.array(z.object({
+      eventOptionId: id,
+      quantity: z.number().int().min(1).max(1000),
+      variantId: id.nullish(),
+      sessionIds: z.array(id).max(200).optional().describe('"Pick sessions" tickets: the sessions chosen'),
+    })).min(1).max(50),
+    guest: z.object({ name: z.string().trim().min(1).max(200), email: z.email().max(200), phone: z.string().trim().max(40).optional() }).optional(),
+    couponCode: z.string().trim().max(60).optional(),
+    attendees: z.array(attendee).max(500).optional().describe('Names for the places (events that collect them)'),
+    ticketDelivery: z.enum(['payer', 'each']).optional().describe('With attendees: tickets to the payer, or to each attendee'),
+    waitlistToken: z.string().max(200).optional(),
+    analyticsSessionId: z.string().max(100).optional(),
+  }),
+  response: single(registrationSummary.extend({
+    isNew: z.boolean().describe('false = added to an existing registration'),
+    couponError: z.string().nullable(),
+  })),
+  async handler({ body, user }) {
+    const { registration, isNew, couponError } = await createRegistration({
+      eventId: body.eventId,
+      options: body.options.map(o => ({ ...o, variantId: o.variantId ?? null })),
+      guestName: body.guest?.name,
+      guestEmail: body.guest?.email,
+      guestPhone: body.guest?.phone,
+      couponCode: body.couponCode,
+      attendees: body.attendees,
+      ticketDelivery: body.ticketDelivery,
+      waitlistToken: body.waitlistToken,
+      analyticsSessionId: body.analyticsSessionId,
+    }, user ? { id: user.id, role: user.role, email: user.email } : null);
+    const fresh = await prisma.registration.findUniqueOrThrow({ where: { id: registration.id }, include: SUMMARY_INCLUDE });
+    return { data: { ...toSummary(fresh), isNew, couponError } };
+  },
+});
+
+export const getRegistration = defineRoute({
+  method: 'get',
+  path: '/registrations/:id',
+  tag: 'Registrations',
+  summary: 'One of my registrations',
+  access: 'user',
+  params: idParams,
+  response: single(registrationSummary),
+  async handler({ params, user }) {
+    return { data: toSummary(await ownRegistration(params.id, user!)) };
+  },
+});
+
+export const cancel = defineRoute({
+  method: 'post',
+  path: '/registrations/:id/cancel',
+  tag: 'Registrations',
+  summary: 'Cancel my registration',
+  description: 'Not after the event has ended, and not once anything has been paid (the church can do that). Its places go to the waitlist.',
+  access: 'user',
+  params: idParams,
+  response: single(registrationSummary),
+  async handler({ params, user, req }) {
+    await ownRegistration(params.id, user!);
+    const { getClientIp } = require('../../utils/requestUtils') as { getClientIp(req: unknown): string };
+    await cancelRegistration(params.id, user!, getClientIp(req));
+    return { data: toSummary(await ownRegistration(params.id, user!)) };
+  },
+});
+
+export const checkout = defineRoute({
+  method: 'post',
+  path: '/registrations/:id/checkout',
+  tag: 'Registrations',
+  summary: 'Pay what I owe online',
+  description: [
+    'Starts a payment with the church\'s provider (Yoco or PayFast) and returns where to send the person (`redirectUrl`).',
+    'If an early-bird price ran out since the registration was made, nothing is started: `priceUpdated` is true with the new amount owing — show it, then call again.',
+  ].join('\n\n'),
+  access: 'user',
+  params: idParams,
+  body: z.object({
+    donationAmount: z.number().min(0).max(100000).optional().describe('An optional donation added on top, in rand'),
+    provider: z.string().max(40).optional().describe('yoco or payfast (default: the first one switched on)'),
+    successUrl: z.url().max(2000).optional(),
+    cancelUrl: z.url().max(2000).optional(),
+    failureUrl: z.url().max(2000).optional(),
+  }),
+  response: single(z.discriminatedUnion('priceUpdated', [
+    z.object({ priceUpdated: z.literal(true), newBalance: z.number(), message: z.string() }),
+    z.object({ priceUpdated: z.literal(false), checkoutId: z.string(), redirectUrl: z.string(), provider: z.string(), amount: z.number().describe('Charged now, in rand (with any donation)') }),
+  ])),
+  async handler({ params, body, user }) {
+    await ownRegistration(params.id, user!);
+    const result = await startRegistrationCheckout(params.id, user!, body);
+    if (result.priceUpdated) return { data: { priceUpdated: true as const, newBalance: result.newTotal, message: result.message } };
+    if (!result.redirectUrl) throw new ApiError('INTERNAL', 'The payment provider did not return a payment page.');
+    return { data: { priceUpdated: false as const, checkoutId: result.checkoutId, redirectUrl: result.redirectUrl, provider: result.provider, amount: result.amount } };
+  },
+});

backend/src/v2/resources/setup.ts

@@ -0,0 +1,229 @@
+import { z } from 'zod';
+import type { Request, RequestHandler } from 'express';
+import { defineRoute } from '../route';
+import { ApiError } from '../errors';
+import { single } from '../paging';
+import { absoluteUrl, id, idParams, isoDate } from '../schemas';
+import * as setup from '../../services/setup';
+import { prisma } from '../legacy';
+import auth from '../../middleware/authMiddleware';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- multer and the scope middleware are JS */
+const campusScope = require('../../utils/campusScope') as {
+  listWhere(req: unknown, path?: string): Promise<object>;
+  scopeEvent(opts?: { need?: 'view' | 'manage'; resolve?: string; from?: (req: any) => unknown }): any;
+};
+const uploads = require('../../controllers/uploadController') as { upload: any; uploadLogo: any; uploadFavicon: any };
+const plain = <T>(v: T): any => JSON.parse(JSON.stringify(v));
+
+// ─── Sections ────────────────────────────────────────────────────────────────
+
+const section = z.looseObject({
+  id, eventId: id, name: z.string(),
+  allowedOptions: z.array(z.looseObject({ eventOptionId: id, eventOption: z.looseObject({ id, name: z.string() }) })),
+});
+
+export const listSections = defineRoute({
+  method: 'get',
+  path: '/sections',
+  tag: 'Events (staff)',
+  summary: 'Scanning sections',
+  description: 'Which ticket types may come in at which door, for one event or every event you can see.',
+  access: 'staff',
+  campusScope: 'scopeList (listWhere)',
+  query: z.object({ eventId: id.optional() }),
+  response: z.object({ data: z.array(section.extend({ event: z.object({ id, title: z.string() }) })) }),
+  async handler({ query, req }) {
+    return { data: plain(await setup.listSections(query.eventId, await campusScope.listWhere(req, 'event'))) };
+  },
+});
+
+export const createSection = defineRoute({
+  method: 'post',
+  path: '/sections',
+  tag: 'Events (staff)',
+  summary: 'Add a scanning section',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(body.eventId, manage)',
+  middleware: [campusScope.scopeEvent({ from: req => req.body?.eventId, need: 'manage' })],
+  status: 201,
+  body: z.object({ eventId: id, name: z.string().trim().min(1).max(120), allowedOptionIds: z.array(id).max(100).optional() }),
+  response: single(section),
+  async handler({ body }) {
+    return { data: plain(await setup.createSection(body)) };
+  },
+});
+
+export const updateSection = defineRoute({
+  method: 'patch',
+  path: '/sections/:id',
+  tag: 'Events (staff)',
+  summary: 'Change a scanning section',
+  description: '`allowedOptionIds`, when sent, replaces its ticket types.',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(section, manage)',
+  middleware: [campusScope.scopeEvent({ resolve: 'section', need: 'manage' })],
+  params: idParams,
+  body: z.object({ name: z.string().trim().min(1).max(120).optional(), allowedOptionIds: z.array(id).max(100).optional() }),
+  response: single(section),
+  async handler({ params, body }) {
+    return { data: plain(await setup.updateSection(params.id, body)) };
+  },
+});
+
+export const deleteSection = defineRoute({
+  method: 'delete',
+  path: '/sections/:id',
+  tag: 'Events (staff)',
+  summary: 'Remove a scanning section',
+  access: 'admin',
+  params: idParams,
+  response: single(z.object({ id, deleted: z.literal(true) })),
+  async handler({ params }) {
+    await setup.deleteSection(params.id);
+    return { data: { id: params.id, deleted: true as const } };
+  },
+});
+
+// ─── Planned costs ───────────────────────────────────────────────────────────
+
+const cost = z.object({
+  id, eventId: id, label: z.string(), costType: z.enum(['once_off', 'per_item']), amount: z.number(),
+  eventOptionId: id.nullable(), eventOption: z.object({ id, name: z.string() }).nullable(),
+  paidFromMethod: z.string().nullable().describe('How it was paid out of the takings (cash, card, eft, other)'),
+  notes: z.string().nullable(), createdAt: isoDate, updatedAt: isoDate.optional(),
+});
+const costBody = z.object({
+  label: z.string().trim().min(1).max(200),
+  costType: z.enum(['once_off', 'per_item']).describe('per_item = per ticket sold of `eventOptionId`'),
+  amount: z.union([z.number().min(0), z.string().max(20)]),
+  eventOptionId: id.nullable().optional(),
+  notes: z.string().max(2000).nullable().optional(),
+  paidFromMethod: z.enum(['cash', 'card', 'eft', 'other']).nullable().optional(),
+});
+
+export const listCosts = defineRoute({
+  method: 'get',
+  path: '/events/:id/costs',
+  tag: 'Events (staff)',
+  summary: 'An event\'s planned costs',
+  access: 'supervisor',
+  campusScope: 'scopeEvent(manage)',
+  middleware: [campusScope.scopeEvent({ need: 'manage' })],
+  params: idParams,
+  response: z.object({ data: z.array(cost) }),
+  async handler({ params }) {
+    return { data: plain(await setup.listCosts(params.id)) };
+  },
+});
+
+export const createCost = defineRoute({
+  method: 'post',
+  path: '/events/:id/costs',
+  tag: 'Events (staff)',
+  summary: 'Add a planned cost',
+  description: 'Admins. Not on a cashed-up event.',
+  access: 'admin',
+  status: 201,
+  params: idParams,
+  body: costBody,
+  response: single(cost),
+  async handler({ params, body }) {
+    return { data: plain(await setup.createCost(params.id, body)) };
+  },
+});
+
+export const updateCost = defineRoute({
+  method: 'patch',
+  path: '/costs/:id',
+  tag: 'Events (staff)',
+  summary: 'Change a planned cost',
+  access: 'admin',
+  params: idParams,
+  body: costBody.partial(),
+  response: single(cost),
+  async handler({ params, body }) {
+    return { data: plain(await setup.updateCost(params.id, body)) };
+  },
+});
+
+export const deleteCost = defineRoute({
+  method: 'delete',
+  path: '/costs/:id',
+  tag: 'Events (staff)',
+  summary: 'Remove a planned cost',
+  access: 'admin',
+  params: idParams,
+  response: single(z.object({ id, deleted: z.literal(true) })),
+  async handler({ params }) {
+    await setup.deleteCost(params.id);
+    return { data: { id: params.id, deleted: true as const } };
+  },
+});
+
+// ─── Image uploads ───────────────────────────────────────────────────────────
+
+/** Runs a multer step for field "image", keeping any error on the request. */
+const receive = (m: any): RequestHandler => (req, res, next) => m.single('image')(req, res, (e: Error | undefined) => {
+  if (e) (req as Request & { multerError?: Error }).multerError = e;
+  next();
+});
+
+/** Branding images: admins — or anyone during first-time setup, before any account exists. */
+const brandingAccess: RequestHandler = async (req, res, next) => {
+  try {
+    if (await prisma.user.count() === 0) return next();
+  } catch { /* fall through to the admin check */ }
+  auth.protect(req, res, (e?: unknown) => (e ? next(e) : auth.admin(req, res, next)));
+};
+
+const uploaded = (folder: string) => async ({ req }: { req: Request }) => {
+  const r = req as Request & { multerError?: Error; file?: { filename: string } };
+  if (r.multerError) throw new ApiError('VALIDATION_FAILED', `Upload failed: ${r.multerError.message}`, { image: r.multerError.message });
+  if (!r.file) throw new ApiError('VALIDATION_FAILED', 'No file uploaded', { image: 'Choose an image' });
+  const path = `/uploads/${folder}/${r.file.filename}`;
+  return { data: { path, url: absoluteUrl(req, path)! } };
+};
+const uploadResult = single(z.object({ path: z.string().describe('What to save on the event or setting'), url: z.string().describe('The same, as a full address') }));
+const IMAGE = 'A JPEG, PNG, GIF or WebP image';
+const LOGO = 'A JPEG, PNG, WebP or SVG image';
+
+export const uploadEventImage = defineRoute({
+  method: 'post',
+  path: '/uploads/event-image',
+  tag: 'Uploads',
+  summary: 'Upload an event picture',
+  description: 'Returns the path to save as the event\'s `picture`.',
+  access: 'supervisor',
+  campusScope: 'campusIndependent (only stores the file; the event is checked when it is saved)',
+  middleware: [receive(uploads.upload)],
+  upload: { field: 'image', description: IMAGE },
+  response: uploadResult,
+  handler: uploaded('events'),
+});
+
+export const uploadLogo = defineRoute({
+  method: 'post',
+  path: '/uploads/logo',
+  tag: 'Uploads',
+  summary: 'Upload the site logo',
+  description: 'Admins — or anyone during first-time setup, before any account exists.',
+  access: 'public',
+  middleware: [brandingAccess, receive(uploads.uploadLogo)],
+  upload: { field: 'image', description: LOGO },
+  response: uploadResult,
+  handler: uploaded('branding'),
+});
+
+export const uploadFavicon = defineRoute({
+  method: 'post',
+  path: '/uploads/favicon',
+  tag: 'Uploads',
+  summary: 'Upload the site icon (favicon)',
+  description: 'Admins — or anyone during first-time setup, before any account exists.',
+  access: 'public',
+  middleware: [brandingAccess, receive(uploads.uploadFavicon)],
+  upload: { field: 'image', description: 'An ICO, PNG or SVG image' },
+  response: uploadResult,
+  handler: uploaded('branding'),
+});

backend/src/v2/route.ts

@@ -0,0 +1,124 @@
+import type { Request, RequestHandler, Response, Router } from 'express';
+import { z } from 'zod';
+import { ApiError } from './errors';
+import auth from '../middleware/authMiddleware';
+
+/**
+ * Every /api/v2 endpoint is declared with `defineRoute`: method, path, who may call it, and zod
+ * schemas for the params, query, body and response. The same declaration
+ *   - validates the request (400 VALIDATION_FAILED with per-field messages),
+ *   - checks the response against its schema and strips anything it doesn't list (so a field
+ *     can't leak by being added to a Prisma include), and
+ *   - becomes the OpenAPI document (openapi.ts) — the docs can't drift from the code.
+ */
+
+export type Access = 'public' | 'optional' | 'user' | 'staff' | 'supervisor' | 'admin';
+
+/** The signed-in person, as the auth middleware puts it on the request. */
+export type ApiUser = { id: string; name: string; email: string; role: 'admin' | 'supervisor' | 'staff' | 'user' };
+
+export type Ctx<P, Q, B> = {
+  params: P;
+  query: Q;
+  body: B;
+  user: ApiUser | null;
+  req: Request;
+  res: Response;
+};
+
+type Schema = z.ZodType;
+type Infer<S> = S extends z.ZodType ? z.infer<S> : undefined;
+
+export type RouteDef<P extends Schema | undefined, Q extends Schema | undefined, B extends Schema | undefined, R extends Schema> = {
+  method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+  /** Express-style, relative to /api/v2: "/events/:id". */
+  path: string;
+  summary: string;
+  description?: string;
+  tag: string;
+  access: Access;
+  /**
+   * Staff and supervisor routes must say how they treat campus-scoped staff (see
+   * utils/campusScope.js and tests/campusScopeRoutes.test.js) — e.g. "scopeEvent(params.id)".
+   */
+  campusScope?: string;
+  params?: P;
+  query?: Q;
+  body?: B;
+  response: R;
+  /** HTTP status on success (default 200). */
+  status?: number;
+  /** Runs after the access check, e.g. a rate limiter. */
+  middleware?: RequestHandler[];
+  /** A multipart upload (the file in `field`, saved by a multer step in `middleware`). */
+  upload?: { field: string; description: string };
+  /**
+   * The answer is a file, not JSON: the handler returns `{ data: { contentType, filename, body } }`
+   * and `response` is `fileResponse`. `contentType` here is what the docs show.
+   */
+  file?: { contentType: string };
+  handler: (ctx: Ctx<Infer<P>, Infer<Q>, Infer<B>>) => Promise<z.input<R>> | z.input<R>;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyRoute = RouteDef<any, any, any, any>;
+
+export const routes: AnyRoute[] = [];
+
+const ACCESS: Record<Access, RequestHandler[]> = {
+  public: [],
+  optional: [auth.optionalAuth],
+  user: [auth.protect],
+  staff: [auth.protect, auth.staff],
+  supervisor: [auth.protect, auth.supervisor],
+  admin: [auth.protect, auth.admin],
+};
+
+export function defineRoute<P extends Schema | undefined, Q extends Schema | undefined, B extends Schema | undefined, R extends Schema>(def: RouteDef<P, Q, B, R>): RouteDef<P, Q, B, R> {
+  if ((def.access === 'staff' || def.access === 'supervisor') && !def.campusScope) {
+    throw new Error(`${def.method.toUpperCase()} /api/v2${def.path}: staff and supervisor routes must declare campusScope`);
+  }
+  routes.push(def as AnyRoute);
+  return def;
+}
+
+const parse = <S extends Schema | undefined>(schema: S, value: unknown): Infer<S> =>
+  (schema ? schema.parse(value) : undefined) as Infer<S>;
+
+/** Adds every defined route to the router. */
+export function mount(router: Router, list: AnyRoute[] = routes): void {
+  for (const def of list) {
+    const run: RequestHandler = async (req, res, next) => {
+      try {
+        const ctx = {
+          params: parse(def.params, req.params),
+          query: parse(def.query, req.query),
+          body: parse(def.body, req.body ?? {}),
+          user: (req as Request & { user?: ApiUser }).user ?? null,
+          req,
+          res,
+        };
+        const result = await def.handler(ctx);
+        const checked = def.response.safeParse(result);
+        if (!checked.success) {
+          console.error(`[api/v2] ${def.method.toUpperCase()} ${def.path}: response doesn't match its schema`, checked.error.issues);
+          throw new ApiError('INTERNAL', 'Something went wrong on the server.');
+        }
+        if (def.file) {
+          const f = (checked.data as { data: { contentType: string; filename: string; body: string } }).data;
+          res.setHeader('Content-Type', f.contentType);
+          res.setHeader('Content-Disposition', `attachment; filename="${f.filename.replace(/"/g, '')}"`);
+          res.status(def.status ?? 200).send(f.body);
+          return;
+        }
+        res.status(def.status ?? 200).json(checked.data);
+      } catch (err) {
+        next(err);
+      }
+    };
+    router[def.method](def.path, ...ACCESS[def.access], ...(def.middleware ?? []), run);
+  }
+}
+
+/** The `response` of a `file` route: what the handler hands back to be sent as a download. */
+export const fileResponse = z.object({ data: z.object({ contentType: z.string(), filename: z.string(), body: z.string() }) });

backend/src/v2/schemas.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import type { Request } from 'express';
+
+/** Shared pieces of v2 schemas. Dates go out as ISO 8601 strings (UTC). */
+
+export const isoDate = z.iso.datetime();
+export const id = z.string().min(1).max(64);
+export const idParams = z.object({ id: id.describe('The id') });
+
+/** A Date (or date string) as ISO 8601, for building responses. */
+export function iso(d: Date | string): string;
+export function iso(d: Date | string | null | undefined): string | null;
+export function iso(d: Date | string | null | undefined): string | null {
+  return d == null ? null : new Date(d).toISOString();
+}
+
+/** A stored picture path ("/uploads/…") as an absolute URL on the host the request came to. */
+export function absoluteUrl(req: Request, url: string | null | undefined): string | null {
+  const raw = String(url || '').trim();
+  if (!raw) return null;
+  if (/^https?:\/\//.test(raw)) return raw;
+  return `${req.protocol}://${req.get('host')}${raw.startsWith('/') ? '' : '/'}${raw}`;
+}
+
+export const campusRef = z.object({ id, name: z.string(), slug: z.string() });
+export const seriesRef = z.object({ id, name: z.string(), slug: z.string() });
+export const eventRef = z.object({ id, title: z.string(), startDate: isoDate, endDate: isoDate });