diff --git a/apps/events/CHANGELOG.md b/apps/events/CHANGELOG.md index e3cda04..745504c 100644 --- a/apps/events/CHANGELOG.md +++ b/apps/events/CHANGELOG.md @@ -50,6 +50,72 @@ and this project follows [Semantic Versioning](https://semver.org/). - `npm run ai:eval` (backend): the helpers' eval set — fixed examples run through the site's Hub connection, with automatic checks on the facts and every answer printed to read. +## [1.52.1] - 2026-11-02 + +### Changed + +- **The API documentation (`/docs/v2`, `GET /api/v2/openapi.json`) now describes every route in + full.** Before, most routes answered by a v1 handler showed an empty body and `data: unknown`. + Each one now documents the body it reads and what it answers, from the handler's actual code, and + every path and query parameter has a description. Actions that take no input say "No body + needed". +- How: `documented: { body?, response? }` on `v1Route` (and `defineRoute`), with shared shapes in + `src/v2/docs.ts`. These are documentation only — requests and answers aren't checked against + them, so nothing an app already does can start failing — but outside production a body or + answer that doesn't fit is logged (`[api/v2] … doesn't match its documented schema`). + `tests/v2Docs.test.ts` keeps the document complete. +- The funnel report's `eventIds` and the webhook deliveries' `status`/`before` filters are now + declared (they worked, but weren't in the document or the typed frontend calls). +- The frontend's generated API types are richer; a few calls had their types tightened to match + (ticket transfer, breach register, kids check-out). Nothing changes in what they send. + +## [1.52.0] - 2026-11-02 — urgent + +### Fixed + +- **Paid door and manual registrations no longer end up without tickets.** On an event with a + required attendee form, tickets wait until a form is in for each person — but At the door and + Manual registration never asked for the form, so payment was recorded and nobody could be checked + in. The form now pops up when someone is registered, selected or pays at the door (and after + registering or paying in Manual registration): fill it in, or **Fill in later**, which issues the + tickets once it's paid and sends the payer a link to the form (`POST + /api/v2/registrations/{id}/form-later`, staff; `Registration.formWaivedAt`). Closing the popup + counts as Fill in later. The door's check-in panel says when a form is holding tickets back. +- **Picked-session bookings needed a form per session.** A person booked on three sessions needed + three forms before their tickets were issued; each person now needs one (`formPlaces` in + `utils/ticketUtils.js`). +- **A required form with only statements and headings held tickets back for ever** (nothing to + answer). Only a required form with a question counts now (`formNeedsAnswers`). Every place that + decided this on its own (coupon making it free, manual and online registration) now asks the + ticket generator (`formsOutstanding`). +- **Self-service kiosk:** it asked for one form per main ticket picked, so a visitor adding to an + existing registration (or booking picked sessions) could finish with the forms still short and + no tickets. It now asks for the forms the server says are missing (`formsNeeded` on `POST + /api/v2/registrations/manual`). Headings on the form showed as an empty text box; they're shown + as text now, with the statements. +- Recording a payment answers `formsNeeded` when a form still holds the tickets back. + +### Added + +- **Corrections** (admins, `/dashboard/admin/corrections`): every registration at an event — + past and closed ones too — with what needs putting right. Issue all missing tickets at once + (forms left for later); fill in a form; issue tickets before payment ("pay later", the balance + is still owed — `Registration.ticketsReleasedAt`); make it free (the balance is written off as a + complimentary discount, `Registration.complimentaryDiscount`, part of `discountTotal`, shown as + "Complimentary" on invoices and receipts; not on closed events); and check a ticket in or undo it + after the event, for any session (a manual check-in, no message sent). Sending the tickets is a + choice. `/api/v2/corrections/…` (admin): `GET events/{id}`, `POST events/{id}/issue-missing`, + `POST registrations/{id}/tickets`, `POST registrations/{id}/complimentary`, + `POST tickets/{id}/check-in`. Code in `src/services/corrections.ts`. +- Audit actions `attendee_form_waived`, `tickets_issued_override`, `registration_complimentary` + and `checkin_corrected`. Migration `20261102120000_corrections`. + +### Upgrading + +- Update before your next event with a required attendee form. After updating, open Admin → + Corrections for a past event to issue any tickets that went missing (leave "Send them" off if + the event is over). + ## [1.51.17] - 2026-10-30 — security release ### Security diff --git a/apps/events/FEATURES.md b/apps/events/FEATURES.md index 3f4867b..fe4b09f 100644 --- a/apps/events/FEATURES.md +++ b/apps/events/FEATURES.md @@ -327,6 +327,12 @@ Feedback → Attendance**. Date, plus Statement and Heading blocks; required/optional, help text, reordering. The whole form can be marked required. - **Drafts** — partially filled forms are auto-saved. +- **Required forms and tickets** — a required form (with at least one question) + holds a registration's tickets back until a form is in for each person (a + picked-session booking counts each person once). At the door and in Manual + registration the form pops up to fill in with the attendee; **Fill in later** + (any staff) issues the tickets anyway once it's paid and sends the payer a link + to the form. The kiosk asks the visitor for exactly the forms still missing. - **Responses** — view, filter (event, user, past/inactive) and print one response per A4 page. Supervisors can edit responses. @@ -492,6 +498,14 @@ logout controls. Disconnected sessions are recovered automatically. 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. +- **Corrections** (`/dashboard/admin/corrections`, admins only) — for any event, + past and closed ones too: registrations missing tickets, with forms to fill in, + or owing money. **Issue all missing tickets** at once (forms left for later), + fill in a form, **issue tickets — pay later** (balance still owed), **make it + free** (the balance written off as a complimentary discount, so income stays + what was paid; not on closed events), and **check people in (or undo) after the + event** for any session. Optionally send the tickets. Every correction is in + the audit log with the reason given. - **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 @@ -938,4 +952,4 @@ can't start, the same jobs run on in-process timers. | `/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 | +| `/dashboard/admin` (+ `/users`, `/registrations`, `/forms`, `/cashup`, `/cashup/[id]`, `/corrections`, `/audit-log`, `/data-requests`, `/privacy`, `/settings`) | Admin | Admin tools | diff --git a/apps/events/WHATS-NEW.md b/apps/events/WHATS-NEW.md index b87b5d5..a3fa280 100644 --- a/apps/events/WHATS-NEW.md +++ b/apps/events/WHATS-NEW.md @@ -12,6 +12,27 @@ Write for church admins, not developers: no environment variables, endpoints or developer log is CHANGELOG.md. A tagged version without a section here shows "No details given". --> +## 1.52.1 + +- **Better documentation for developers.** If someone builds on your Cross Events site (for example + an integration or a website plug-in), the API reference now explains every part of it in full. + Nothing changes in how the site works. + +## 1.52.0 — urgent + +- **Paying at the door always gives people their tickets now.** On events with a required + attendee form, people registered at the door or in Manual registration were paid but got no + tickets, so they couldn't be checked in. The form now pops up to fill in with them — or tap + **Fill in later**: the tickets are issued straight away and they're sent a link to fill in the + form afterwards. +- **New: Corrections (for admins).** Pick any event, even one that's over, to see who's missing + tickets, still has a form to fill in or owes money. Issue all missing tickets in one click, give + someone their tickets now and let them pay later, make a ticket free, or check people in after + the event. +- The self-service kiosk asks for exactly the forms still needed, and shows headings on the form + as text instead of an empty box. +- People booked on several sessions now fill in one form each, not one per session. + ## 1.51.17 — security update - **Better protection for people's accounts.** The forgot-password and sign-in pages no longer diff --git a/apps/events/backend/package-lock.json b/apps/events/backend/package-lock.json index 2c49bba..e58dae9 100644 --- a/apps/events/backend/package-lock.json +++ b/apps/events/backend/package-lock.json @@ -1,12 +1,12 @@ { "name": "event-management-backend", - "version": "1.51.17", + "version": "1.52.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "event-management-backend", - "version": "1.51.17", + "version": "1.52.1", "hasInstallScript": true, "dependencies": { "@cj-tech-master/excelts": "^10.2.0", diff --git a/apps/events/backend/package.json b/apps/events/backend/package.json index 6941722..f5f3914 100644 --- a/apps/events/backend/package.json +++ b/apps/events/backend/package.json @@ -1,6 +1,6 @@ { "name": "event-management-backend", - "version": "1.51.17", + "version": "1.52.1", "description": "Event Management System Backend", "main": "src/index.js", "scripts": { diff --git a/apps/events/backend/prisma/migrations/20261102120000_corrections/migration.sql b/apps/events/backend/prisma/migrations/20261102120000_corrections/migration.sql new file mode 100644 index 0000000..0944860 --- /dev/null +++ b/apps/events/backend/prisma/migrations/20261102120000_corrections/migration.sql @@ -0,0 +1,12 @@ +-- AlterEnum +ALTER TYPE "AdminAuditAction" ADD VALUE 'attendee_form_waived'; +ALTER TYPE "AdminAuditAction" ADD VALUE 'tickets_issued_override'; +ALTER TYPE "AdminAuditAction" ADD VALUE 'registration_complimentary'; +ALTER TYPE "AdminAuditAction" ADD VALUE 'checkin_corrected'; + +-- AlterTable +ALTER TABLE "Registration" ADD COLUMN "formWaivedAt" TIMESTAMP(3), +ADD COLUMN "formWaivedById" TEXT, +ADD COLUMN "ticketsReleasedAt" TIMESTAMP(3), +ADD COLUMN "ticketsReleasedById" TEXT, +ADD COLUMN "complimentaryDiscount" DOUBLE PRECISION NOT NULL DEFAULT 0; diff --git a/apps/events/backend/prisma/schema.prisma b/apps/events/backend/prisma/schema.prisma index a74abac..b536537 100644 --- a/apps/events/backend/prisma/schema.prisma +++ b/apps/events/backend/prisma/schema.prisma @@ -506,6 +506,15 @@ model Registration { bundleDiscount Float @default(0) // Where named attendees' tickets go: all to the payer, or each to the attendee. ticketDelivery TicketDelivery @default(payer) + // Corrections (1.52.0). The attendee form can come later: tickets don't wait for it ("Fill in + // later" at the door or in Manual registrations, or an admin in Corrections). + formWaivedAt DateTime? + formWaivedById String? + // An admin issued the tickets before it was paid ("pay later"): the balance is still owed. + ticketsReleasedAt DateTime? + ticketsReleasedById String? + // A balance an admin wrote off ("make it free"); part of discountTotal (utils/coupons.js). + complimentaryDiscount Float @default(0) analyticsSessionId String? createdAt DateTime @default(now()) updatedAt DateTime @updatedAt @@ -779,6 +788,10 @@ enum AdminAuditAction { event_sessions_changed attendance_marked attendance_unmarked + attendee_form_waived + tickets_issued_override + registration_complimentary + checkin_corrected certificate_issued certificate_revoked job_run_manual diff --git a/apps/events/backend/src/controllers/paymentController.js b/apps/events/backend/src/controllers/paymentController.js index 1917520..0a9a3ab 100644 --- a/apps/events/backend/src/controllers/paymentController.js +++ b/apps/events/backend/src/controllers/paymentController.js @@ -1,6 +1,6 @@ const prisma = require('../config/db'); const { v4: uuidv4 } = require('uuid'); -const { generateTicketsForRegistration } = require('../utils/ticketUtils'); +const { generateTicketsForRegistration, formsOutstanding } = require('../utils/ticketUtils'); const { computeRegistrationTotalDue, refreshPricingForRegistration } = require('../utils/pricing'); const { computeDonationRemaining } = require('../utils/donationUtils'); const { logAdminAction } = require('../utils/adminAudit'); @@ -238,7 +238,9 @@ const createPayment = async (req, res) => { // If it's a registration payment, update registration status let updatedRegistration = null; let generatedTickets = []; - + // Attendee forms still holding the tickets back (the door offers them, or "Fill in later"). + let formsNeeded = 0; + if (registrationId) { const registration = await prisma.registration.findUnique({ where: { id: registrationId }, @@ -284,6 +286,7 @@ const createPayment = async (req, res) => { } catch (error) { console.error('Error generating tickets:', error); } + formsNeeded = await formsOutstanding(registrationId); } } @@ -318,6 +321,7 @@ const createPayment = async (req, res) => { ...updatedRegistration }, generatedTickets: generatedTickets.length > 0 ? generatedTickets : undefined, + formsNeeded, donationSplit: donationSplit || undefined }; res.status(201).json(paymentWithUpdatedRegistration); diff --git a/apps/events/backend/src/services/corrections.ts b/apps/events/backend/src/services/corrections.ts new file mode 100644 index 0000000..ed85604 --- /dev/null +++ b/apps/events/backend/src/services/corrections.ts @@ -0,0 +1,345 @@ +/** + * Corrections (1.52.0): putting registrations right when the normal flow didn't finish — tickets + * held back by a required attendee form, tickets needed before it's paid, a balance to write off, + * and check-ins after the event. Admins only, from Corrections; "Fill in later" (leaveFormForLater) + * is for any staff at the door and in Manual registrations. + * + * Every change is in the audit log with who did it and the reason given. + */ +import { prisma as typedPrisma } from '../v2/legacy'; +import { fail } from './errors'; + +/* eslint-disable @typescript-eslint/no-explicit-any -- the records are Prisma's with includes */ +const prisma = typedPrisma as any; +const { generateTicketsForRegistration, formsOutstanding, formPlaces, formNeedsAnswers } = require('../utils/ticketUtils') as { + generateTicketsForRegistration(id: string): Promise; + formsOutstanding(registration: string | object): Promise; + formPlaces(registrationOptions: any[]): number; + formNeedsAnswers(form: any): boolean; +}; +const { computeRegistrationTotalDue } = require('../utils/pricing') as { computeRegistrationTotalDue(registration: any, at: Date): number }; +const { recalculateRegistrationDiscount } = require('../utils/coupons') as { recalculateRegistrationDiscount(id: string): Promise }; +const { assertEventOpen } = require('../utils/cashupUtils') as { assertEventOpen(eventId: string): Promise }; +const { logAdminAction } = require('../utils/adminAudit') as { logAdminAction(entry: object): Promise }; +const sessions = require('../utils/sessions') as { + activeSessions(sessions: any[]): any[]; + sessionLabel(session: any, sessions: any[]): string; + lineCovers(line: any, sessionId: string): boolean; + lineSessions(line: any): string[] | null; + redeemedForSession(usages: any[], sessionId: string | null): number; +}; + +export type Actor = { id: string; role: string }; +type Audit = { actor: Actor; ip?: string }; + +/** The key a single-date event's check-ins are counted under. */ +export const WHOLE_EVENT = 'event'; + +const round2 = (n: number) => Math.round(n * 100) / 100; +const realEmail = (email: string | null | undefined) => (email && !email.endsWith('@guest.local') ? email : null); + +const REGISTRATION_INCLUDE = { + user: { select: { id: true, name: true, email: true, phoneNumber: true } }, + payments: { select: { amount: true, createdAt: true } }, + formResponses: { select: { id: true } }, + attendees: { select: { id: true, name: true } }, + registrationOptions: { + include: { + eventOption: { include: { earlyBirdTiers: true } }, + variant: { select: { name: true } }, + tranches: true, + tickets: { + include: { usages: { select: { quantityRedeemed: true, sessionId: true } }, attendee: { select: { name: true } }, holder: { select: { name: true } } }, + orderBy: { createdAt: 'asc' }, + }, + }, + }, +}; + +async function emailTicketsTo(registrationId: string, userId: string) { + const { emailTickets } = require('../controllers/ticketController') as { emailTickets(req: any, res: any): Promise }; + const res: any = { status: () => res, json: () => {} }; + try { + await emailTickets({ user: { id: userId }, body: { registrationId } }, res); + } catch (e: any) { + console.error('[corrections] Failed to send tickets:', e?.message || e); + } +} + +async function loadEvent(eventId: string) { + const event = await prisma.event.findUnique({ + where: { id: eventId }, + select: { + id: true, title: true, startDate: true, endDate: true, scheduleType: true, cashupStatus: true, + sessions: { select: { id: true, label: true, startsAt: true, endsAt: true, cancelledAt: true } }, + form: { include: { fields: { select: { type: true } } } }, + }, + }); + return event || fail(404, 'Event not found'); +} + +/** One registration as Corrections shows it: money, forms, tickets and their check-ins. */ +function correctionRow(reg: any, event: any, formRequired: boolean) { + const now = new Date(); + const totalDue = round2(computeRegistrationTotalDue(reg, now)); + const paid = round2((reg.payments || []).reduce((s: number, p: any) => s + (p.amount || 0), 0)); + const active = sessions.activeSessions(event.sessions || []); + const multi = event.scheduleType === 'sessions'; + let places = 0; + let ticketPlaces = 0; + const tickets: any[] = []; + for (const ro of reg.registrationOptions || []) { + places += ro.quantity || 0; + const session = ro.sessionId ? active.find((s: any) => s.id === ro.sessionId) : null; + const label = [ro.eventOption?.name, ro.variant?.name].filter(Boolean).join(' — ') + + (session ? ` (${sessions.sessionLabel(session, event.sessions)})` : ''); + for (const t of ro.tickets || []) { + ticketPlaces += t.quantity || 0; + const covered = multi ? (sessions.lineSessions(ro) ?? active.map((s: any) => s.id)).filter((id: string) => active.some((s: any) => s.id === id)) : [WHOLE_EVENT]; + const checkedIn: Record = {}; + for (const key of covered) checkedIn[key] = sessions.redeemedForSession(t.usages, multi ? key : null); + tickets.push({ + id: t.id, + qrCode: t.qrCode, + label, + isMainTicket: !!ro.eventOption?.isMainTicket, + name: t.attendee?.name || t.holder?.name || reg.user?.name || '', + quantity: t.quantity || 1, + sessionIds: covered, + checkedIn, + }); + } + } + const ticketsDue = reg.status === 'paid' || !!reg.ticketsReleasedAt; + const formsNeeded = formRequired && !reg.formWaivedAt ? Math.max(0, formPlaces(reg.registrationOptions) - (reg.formResponses || []).length) : 0; + return { + id: reg.id, + status: reg.status, + createdAt: reg.createdAt, + user: { id: reg.user?.id, name: reg.user?.name || '', email: realEmail(reg.user?.email), phoneNumber: reg.user?.phoneNumber || null }, + totalDue, + paid, + balance: round2(Math.max(0, totalDue - paid)), + places, + ticketPlaces, + missingTickets: ticketsDue && ticketPlaces < places, + formsNeeded, + formWaived: !!reg.formWaivedAt, + ticketsReleased: !!reg.ticketsReleasedAt, + complimentary: Number(reg.complimentaryDiscount || 0), + tickets, + }; +} + +function eventSummary(event: any) { + const active = sessions.activeSessions(event.sessions || []); + return { + id: event.id, + title: event.title, + startDate: event.startDate, + endDate: event.endDate, + closed: event.cashupStatus === 'closed', + formRequired: formNeedsAnswers(event.form), + sessions: event.scheduleType === 'sessions' + ? active.map((s: any) => ({ id: s.id, label: sessions.sessionLabel(s, event.sessions), startsAt: s.startsAt })) + : [], + }; +} + +/** An event's registrations (not cancelled) with what may need putting right. */ +export async function eventCorrections(eventId: string) { + const event = await loadEvent(eventId); + const formRequired = formNeedsAnswers(event.form); + const regs = await prisma.registration.findMany({ + where: { eventId, status: { not: 'cancelled' } }, + include: REGISTRATION_INCLUDE, + orderBy: { createdAt: 'asc' }, + }); + return { event: eventSummary(event), registrations: regs.map((r: any) => correctionRow(r, event, formRequired)) }; +} + +async function registrationRow(registrationId: string) { + const reg = await prisma.registration.findUnique({ where: { id: registrationId }, include: REGISTRATION_INCLUDE }); + if (!reg) return fail(404, 'Registration not found'); + const event = await loadEvent(reg.eventId); + return correctionRow(reg, event, formNeedsAnswers(event.form)); +} + +async function activeRegistration(registrationId: string) { + const reg = await prisma.registration.findUnique({ where: { id: registrationId }, include: { registrationOptions: { include: { eventOption: true } } } }); + if (!reg) return fail(404, 'Registration not found'); + if (reg.status === 'cancelled') return fail(400, 'This registration is cancelled.'); + return reg; +} + +async function waiveForm(reg: any, actorId: string) { + if (reg.formWaivedAt || (await formsOutstanding(reg)) === 0) return false; + await prisma.registration.update({ where: { id: reg.id }, data: { formWaivedAt: new Date(), formWaivedById: actorId, updatedAt: new Date() } }); + return true; +} + +/** + * "Fill in later" at the door / in Manual registrations: the tickets stop waiting for the + * attendee form, and the payer is sent a link to fill it in (`notify`). + */ +export async function leaveFormForLater(registrationId: string, { actor, ip }: Audit, { notify = true }: { notify?: boolean } = {}) { + const reg = await activeRegistration(registrationId); + const waived = await waiveForm(reg, actor.id); + const created = await generateTicketsForRegistration(reg.id); + if (created.length > 0) await emailTicketsTo(reg.id, reg.userId); + let sentTo: string[] = []; + if (waived) { + logAdminAction({ actorId: actor.id, actorRole: actor.role, action: 'attendee_form_waived', targetType: 'Registration', targetId: reg.id, metadata: { eventId: reg.eventId, from: 'door' }, ip }); + if (notify) { + const { sendFormReminderMessage } = require('../utils/notifications') as { sendFormReminderMessage(id: string): Promise }; + sentTo = await sendFormReminderMessage(reg.id).catch(() => []); + } + } + return { ticketsIssued: created.length, sentTo }; +} + +type IssueOptions = { skipForm?: boolean; payLater?: boolean; send?: boolean; reason?: string | null }; + +/** + * Admin: issue a registration's tickets now — leaving the attendee form for later (`skipForm`) + * and/or before it's paid (`payLater`, the balance is still owed). + */ +export async function issueTickets(registrationId: string, { actor, ip }: Audit, opts: IssueOptions) { + const reg = await activeRegistration(registrationId); + if (reg.status !== 'paid' && !reg.ticketsReleasedAt && !opts.payLater) { + return fail(400, 'This registration isn\'t paid yet. Choose "pay later" or "make it free" to issue its tickets.'); + } + const outstanding = opts.skipForm ? 0 : await formsOutstanding(reg); + if (outstanding > 0) { + return fail(400, `${outstanding} attendee form${outstanding === 1 ? ' is' : 's are'} still to fill in. Fill ${outstanding === 1 ? 'it' : 'them'} in, or choose to leave the form for later.`); + } + const waived = opts.skipForm ? await waiveForm(reg, actor.id) : false; + const released = !!opts.payLater && reg.status !== 'paid' && !reg.ticketsReleasedAt; + if (released) { + await prisma.registration.update({ where: { id: reg.id }, data: { ticketsReleasedAt: new Date(), ticketsReleasedById: actor.id, updatedAt: new Date() } }); + } + const created = await generateTicketsForRegistration(reg.id); + logAdminAction({ + actorId: actor.id, actorRole: actor.role, action: 'tickets_issued_override', targetType: 'Registration', targetId: reg.id, + metadata: { eventId: reg.eventId, formLeftForLater: waived, payLater: released, ticketsCreated: created.length, reason: opts.reason || null }, + ip, + }); + if (opts.send && created.length > 0) await emailTicketsTo(reg.id, reg.userId); + if (waived) logAdminAction({ actorId: actor.id, actorRole: actor.role, action: 'attendee_form_waived', targetType: 'Registration', targetId: reg.id, metadata: { eventId: reg.eventId, from: 'corrections', reason: opts.reason || null }, ip }); + return { ticketsIssued: created.length, registration: await registrationRow(reg.id) }; +} + +/** + * Admin: write off what's still owed ("make it free") — it comes off as a complimentary + * discount, so income stays what was really paid — and issue the tickets. + */ +export async function makeComplimentary(registrationId: string, { actor, ip }: Audit, opts: Omit) { + const reg = await activeRegistration(registrationId); + try { + await assertEventOpen(reg.eventId); + } catch (e: any) { + return fail(400, e?.message || 'This event is closed.'); + } + const full = await prisma.registration.findUnique({ + where: { id: reg.id }, + include: { registrationOptions: { include: { eventOption: { include: { earlyBirdTiers: true } }, tranches: true } }, payments: true }, + }); + const due = computeRegistrationTotalDue(full, new Date()); + const paid = (full.payments || []).reduce((s: number, p: any) => s + (p.amount || 0), 0); + const balance = round2(due - paid); + if (!(balance > 0.004)) return fail(400, 'Nothing is owed on this registration.'); + + await prisma.registration.update({ where: { id: reg.id }, data: { complimentaryDiscount: round2(Number(full.complimentaryDiscount || 0) + balance), updatedAt: new Date() } }); + await recalculateRegistrationDiscount(reg.id); + await prisma.registration.update({ where: { id: reg.id }, data: { status: 'paid', updatedAt: new Date() } }); + logAdminAction({ + actorId: actor.id, actorRole: actor.role, action: 'registration_complimentary', targetType: 'Registration', targetId: reg.id, + metadata: { eventId: reg.eventId, amount: balance, reason: opts.reason || null }, ip, + }); + + const waived = opts.skipForm ? await waiveForm(reg, actor.id) : false; + if (waived) logAdminAction({ actorId: actor.id, actorRole: actor.role, action: 'attendee_form_waived', targetType: 'Registration', targetId: reg.id, metadata: { eventId: reg.eventId, from: 'corrections', reason: opts.reason || null }, ip }); + const created = await generateTicketsForRegistration(reg.id); + if (opts.send && created.length > 0) await emailTicketsTo(reg.id, reg.userId); + return { amount: balance, ticketsIssued: created.length, registration: await registrationRow(reg.id) }; +} + +/** + * Admin: every paid registration (or one released unpaid) at an event that's missing tickets + * gets them — forms still outstanding are left for later. + */ +export async function issueMissingTickets(eventId: string, { actor, ip }: Audit, { send = false }: { send?: boolean } = {}) { + const { registrations } = await eventCorrections(eventId); + const missing = registrations.filter((r: any) => r.missingTickets); + let tickets = 0; + let fixed = 0; + const failed: { id: string; name: string; message: string }[] = []; + for (const row of missing) { + try { + const reg = await activeRegistration(row.id); + await waiveForm(reg, actor.id); + const created = await generateTicketsForRegistration(reg.id); + tickets += created.length; + if (created.length > 0) fixed += 1; + if (send && created.length > 0) await emailTicketsTo(reg.id, reg.userId); + } catch (e: any) { + failed.push({ id: row.id, name: row.user.name, message: e?.message || 'Failed' }); + } + } + if (missing.length > 0) { + logAdminAction({ + actorId: actor.id, actorRole: actor.role, action: 'tickets_issued_override', targetType: 'Event', targetId: eventId, + metadata: { registrations: fixed, ticketsCreated: tickets, formLeftForLater: true, sent: send, failed: failed.length }, ip, + }); + } + return { registrations: fixed, tickets, failed }; +} + +type CheckInOptions = { sessionId?: string | null; people?: number | null; present?: boolean; reason?: string | null }; + +/** + * Admin: check a ticket in (or undo it) whatever the time — after the event or session has + * ended, outside the check-in window, or once the event is closed. Recorded as a manual + * check-in; no check-in message is sent. + */ +export async function correctCheckIn(ticketId: string, { actor, ip }: Audit, opts: CheckInOptions) { + const ticket = await prisma.ticket.findUnique({ + where: { id: ticketId }, + include: { usages: true, event: { select: { id: true, scheduleType: true } }, registrationOption: { select: { sessionId: true, sessionIds: true, registration: { select: { status: true } } } } }, + }); + if (!ticket) return fail(404, 'Ticket not found'); + if (ticket.registrationOption?.registration?.status === 'cancelled') return fail(400, 'This registration is cancelled.'); + const multi = ticket.event.scheduleType === 'sessions'; + let sessionId: string | null = null; + if (multi) { + const session = opts.sessionId ? await prisma.eventSession.findUnique({ where: { id: opts.sessionId } }) : null; + if (!session || session.eventId !== ticket.eventId) return fail(400, 'Choose one of this event\'s sessions.'); + if (session.cancelledAt) return fail(400, 'That session was cancelled.'); + if (ticket.registrationOption && !sessions.lineCovers(ticket.registrationOption, session.id)) return fail(400, 'That ticket isn\'t booked for this session.'); + sessionId = session.id; + } + + const forSession = ticket.usages.filter((u: any) => (u.sessionId || null) === sessionId); + const redeemed = sessions.redeemedForSession(ticket.usages, sessionId); + const quantity = ticket.quantity || 1; + let changed = 0; + if (opts.present === false) { + if (forSession.length === 0) return fail(400, 'This ticket isn\'t checked in.'); + await prisma.ticketUsage.deleteMany({ where: { id: { in: forSession.map((u: any) => u.id) } } }); + if (!multi) await prisma.ticket.update({ where: { id: ticket.id }, data: { isUsed: false, updatedAt: new Date() } }); + changed = redeemed; + } else { + const left = quantity - redeemed; + if (left <= 0) return fail(400, 'Everyone on this ticket is already checked in.'); + const people = Math.min(Math.max(1, Math.trunc(Number(opts.people)) || left), left); + await prisma.ticketUsage.create({ data: { ticketId: ticket.id, scannedById: actor.id, quantityRedeemed: people, sessionId, manual: true } }); + if (!multi && redeemed + people >= quantity) await prisma.ticket.update({ where: { id: ticket.id }, data: { isUsed: true, updatedAt: new Date() } }); + changed = people; + } + logAdminAction({ + actorId: actor.id, actorRole: actor.role, action: 'checkin_corrected', targetType: 'Ticket', targetId: ticket.id, + metadata: { eventId: ticket.eventId, sessionId, present: opts.present !== false, people: changed, reason: opts.reason || null }, ip, + }); + const after = await prisma.ticketUsage.findMany({ where: { ticketId: ticket.id }, select: { quantityRedeemed: true, sessionId: true } }); + return { checkedIn: sessions.redeemedForSession(after, sessionId), quantity }; +} diff --git a/apps/events/backend/src/services/registrationAdmin.ts b/apps/events/backend/src/services/registrationAdmin.ts index 0d1f2f1..e21b57b 100644 --- a/apps/events/backend/src/services/registrationAdmin.ts +++ b/apps/events/backend/src/services/registrationAdmin.ts @@ -18,7 +18,10 @@ import { /* eslint-disable @typescript-eslint/no-explicit-any -- moved from JavaScript; the records are Prisma's with includes */ // The queries below build their includes and data step by step, as the JavaScript did. const prisma = typedPrisma as any; -const { generateTicketsForRegistration } = require('../utils/ticketUtils') as { generateTicketsForRegistration(id: string): Promise }; +const { generateTicketsForRegistration, formsOutstanding } = require('../utils/ticketUtils') as { + generateTicketsForRegistration(id: string): Promise; + formsOutstanding(registration: string | object): Promise; +}; const { emailTickets } = require('../controllers/ticketController') as { emailTickets(req: any, res: any): Promise }; const { hashPassword } = require('../config/auth') as { hashPassword(p: string): Promise }; const { computeRegistrationTotalDue, refreshPricingForRegistration, attachComputedTotals, attachComputedTotalsToList } = require('../utils/pricing') as { @@ -111,13 +114,9 @@ async function syncStatusAfterDiscount(registrationId: string) { if (status === 'paid' && reg.status !== 'paid') { (async () => { try { - let hasRequiredForm = false; - try { - const form = await prisma.eventForm.findUnique({ where: { eventId: reg.eventId } }); - hasRequiredForm = !!(form && form.isRequired); - } catch {} - if (hasRequiredForm) return; - await generateTicketsForRegistration(registrationId); + // Waits while a required attendee form is outstanding (see utils/ticketUtils). + const created = await generateTicketsForRegistration(registrationId); + if (created.length === 0) return; const mockReq = { user: { id: reg.userId }, body: { registrationId } }; const mockRes = { status: () => mockRes, json: () => {} }; await emailTickets(mockReq, mockRes); @@ -840,13 +839,6 @@ export const createManualRegistration = as400(async (call: Call): Promise = }); } - // Auto mark paid and generate tickets if free and no required form (new registrations only) - let hasRequiredForm = false; - try { - const form = await prisma.eventForm.findUnique({ where: { eventId: registration.eventId } }); - hasRequiredForm = !!(form && form.isRequired); - } catch {} - // Auto-mark paid and generate tickets for free registrations (new OR existing that became free) if (registration.status !== 'paid') try { const totalDue = computeRegistrationTotalDue(registration, new Date()); @@ -856,7 +848,12 @@ export const createManualRegistration = as400(async (call: Call): Promise = } } catch {} - // Generate/sync tickets for all paid registrations that have no required form + // Attendee forms still to fill in (a required form holds the tickets back until they're in, + // or until staff choose "Fill in later" — POST /registrations/:id/form-later). + const formsNeeded = await formsOutstanding(registration.id); + const hasRequiredForm = formsNeeded > 0; + + // Generate/sync tickets for all paid registrations that aren't waiting for a form if (registration.status === 'paid' && !hasRequiredForm) try { await generateTicketsForRegistration(registration.id); } catch {} @@ -912,7 +909,7 @@ export const createManualRegistration = as400(async (call: Call): Promise = ip: call.ip, }); - return { ...attachComputedTotals(registration), ...(couponError ? { couponError } : {}) }; + return { ...attachComputedTotals(registration), formsNeeded, ...(couponError ? { couponError } : {}) }; }); // @desc Update registration options (add/remove items) with constraints @@ -1359,11 +1356,12 @@ export const submitFormResponses = as400(async (call: Call): Promise => { created.push(fr); } - // After submitting responses, if registration is already paid, generate and email tickets now. + // After submitting responses, if registration is already paid (or its tickets were released + // unpaid), generate and email tickets now. let generatedTickets = []; try { const regAfter = await prisma.registration.findUnique({ where: { id: registrationId } }); - if (regAfter && regAfter.status === 'paid') { + if (regAfter && (regAfter.status === 'paid' || regAfter.ticketsReleasedAt)) { generatedTickets = await generateTicketsForRegistration(registrationId); if (generatedTickets && generatedTickets.length > 0) { try { @@ -1449,7 +1447,7 @@ export const replaceFormResponses = as400(async (call: Call): Promise => { // Attempt ticket generation and email if already paid try { const regAfter = await prisma.registration.findUnique({ where: { id: registrationId }, include: { user: { select: { id: true } } } }); - if (regAfter && regAfter.status === 'paid') { + if (regAfter && (regAfter.status === 'paid' || regAfter.ticketsReleasedAt)) { const newTickets = await generateTicketsForRegistration(registrationId); if (newTickets && newTickets.length > 0) { try { diff --git a/apps/events/backend/src/services/registrations.ts b/apps/events/backend/src/services/registrations.ts index a54439f..e6d9fb2 100644 --- a/apps/events/backend/src/services/registrations.ts +++ b/apps/events/backend/src/services/registrations.ts @@ -8,7 +8,10 @@ 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 }; +const { generateTicketsForRegistration, formsOutstanding } = require('../utils/ticketUtils') as { + generateTicketsForRegistration(id: string): Promise; + formsOutstanding(registration: string | object): Promise; +}; 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 }>; @@ -410,8 +413,7 @@ async function create(input: CreateRegistrationInput, actor: Actor) { 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)) { + if ((await formsOutstanding(registrationId)) === 0) { // Same generator as paid registrations: a ticket per named attendee, and one // shared quantity ticket for the rest of each line. await generateTicketsForRegistration(registrationId); diff --git a/apps/events/backend/src/utils/coupons.js b/apps/events/backend/src/utils/coupons.js index 23004a6..4a52ae1 100644 --- a/apps/events/backend/src/utils/coupons.js +++ b/apps/events/backend/src/utils/coupons.js @@ -256,7 +256,8 @@ async function registrationBundles(registration, db = prisma) { * left. Percentage and comp codes are recalculated over the new items, fixed codes keep * their amount (capped at what's still in scope). `keepCouponAmounts` keeps every * coupon's amount (capped the same way): used when only prices changed, e.g. an - * early-bird tier expiring. Updates bundleDiscount and discountTotal and returns + * early-bird tier expiring. A balance an admin wrote off (`complimentaryDiscount`, 1.52.0) + * comes off last, as a fixed amount. Updates bundleDiscount and discountTotal and returns * discountTotal. Pass `tx` to run inside the caller's transaction. */ async function recalculateRegistrationDiscount(registrationId, db = prisma, { keepCouponAmounts = false } = {}) { @@ -280,7 +281,7 @@ async function recalculateRegistrationDiscount(registrationId, db = prisma, { ke } total += amount; } - total = round2(total); + total = round2(total + Number(registration.complimentaryDiscount || 0)); if (Math.abs(total - registration.discountTotal) > 0.001 || Math.abs(bundles.discount - registration.bundleDiscount) > 0.001) { await db.registration.update({ where: { id: registrationId }, data: { discountTotal: total, bundleDiscount: bundles.discount } }); } diff --git a/apps/events/backend/src/utils/notifications.js b/apps/events/backend/src/utils/notifications.js index a0e65f6..2e3178d 100644 --- a/apps/events/backend/src/utils/notifications.js +++ b/apps/events/backend/src/utils/notifications.js @@ -1512,10 +1512,49 @@ async function sendAttendeeFormLinkMessage(attendee) { return sent; } +// "Fill in later" (1.52.0): the attendee form was left for later at the door, so the payer is +// sent a link to the forms still to do — by email and/or WhatsApp as they prefer. +async function sendFormReminderMessage(registrationId) { + const org = getOrg(); + const reg = await prisma.registration.findUnique({ where: { id: registrationId }, include: { event: { select: { title: true } }, user: true } }); + if (!reg || !reg.user) return []; + const { shouldEmail, waText, canWhatsApp } = require('./notify'); + const eventTitle = reg.event?.title || 'the event'; + const link = `${org.url}/forms?registrationId=${encodeURIComponent(reg.id)}`; + const sent = []; + + if (reg.user.email && !reg.user.email.endsWith('@guest.local') && shouldEmail(reg.user)) { + const html = emailWrapper(` +

Please fill in your attendee form

+

Hi ${reg.user.name},

+

Thanks for registering for ${eventTitle}. We still need the attendee form — it only takes a minute.

+ ${ctaButton('Fill in the form', link)} + ${fallbackLink(link)} + `, { preheader: `Your attendee form for ${eventTitle}` }); + try { + await sendMail({ to: reg.user.email, subject: `Your attendee form for ${eventTitle}`, html, text: `Hi ${reg.user.name}, + +Thanks for registering for ${eventTitle}. We still need the attendee form: +${link} + +${org.name}` }); + sent.push('email'); + } catch (e) { + console.warn('[form reminder] email failed:', e?.message || e); + } + } + if (canWhatsApp(reg.user)) { + await waText(reg.user, `Hi ${reg.user.name}, thanks for registering for *${eventTitle}*. We still need your attendee form: ${link}`); + sent.push('WhatsApp'); + } + return sent; +} + module.exports = { getEventNotifyEmails, buildEventNotifyRecipientList, sendAttendeeFormLinkMessage, + sendFormReminderMessage, sendRegistrationEmails, sendRegistrationUpdatedEmails, sendPaymentEmails, diff --git a/apps/events/backend/src/utils/pdfDocs.js b/apps/events/backend/src/utils/pdfDocs.js index f26eead..f1f78d1 100644 --- a/apps/events/backend/src/utils/pdfDocs.js +++ b/apps/events/backend/src/utils/pdfDocs.js @@ -96,10 +96,10 @@ function buildLineItems(registrationOptions) { /** * The registration's coupon discount and a label naming the code(s), e.g. "Code STAFF50". * Needs `couponRedemptions[].coupon.code` loaded for the label; the amount is - * Registration.discountTotal less the bundle part, both always present. + * Registration.discountTotal less the bundle and complimentary parts, all always present. */ function couponDiscountLine(registration) { - const amount = Math.round((Number(registration?.discountTotal || 0) - Number(registration?.bundleDiscount || 0)) * 100) / 100; + const amount = Math.round((Number(registration?.discountTotal || 0) - Number(registration?.bundleDiscount || 0) - Number(registration?.complimentaryDiscount || 0)) * 100) / 100; if (!(amount > 0.001)) return null; const codes = (registration.couponRedemptions || []).map(r => r.coupon?.code).filter(Boolean); return { amount, label: codes.length ? `Code ${codes.join(', ')}` : 'Discount code' }; @@ -118,9 +118,15 @@ function bundleDiscountLine(registration) { return { amount, label: names.length ? `Bundle: ${names.join(', ')}` : 'Bundle deal' }; } -/** Bundle saving then coupon discount, as display lines ({ label, amount }). */ +/** A balance written off by an admin (Corrections → Make it free, 1.52.0). */ +function complimentaryLine(registration) { + const amount = Number(registration?.complimentaryDiscount || 0); + return amount > 0.001 ? { amount, label: 'Complimentary' } : null; +} + +/** Bundle saving, coupon discount, then anything made complimentary, as display lines ({ label, amount }). */ function discountLines(registration) { - return [bundleDiscountLine(registration), couponDiscountLine(registration)].filter(Boolean); + return [bundleDiscountLine(registration), couponDiscountLine(registration), complimentaryLine(registration)].filter(Boolean); } /** Draws a two-column item table starting at `y`; returns the y position after the last row. */ diff --git a/apps/events/backend/src/utils/ticketUtils.js b/apps/events/backend/src/utils/ticketUtils.js index 4242d75..d7ef6d4 100644 --- a/apps/events/backend/src/utils/ticketUtils.js +++ b/apps/events/backend/src/utils/ticketUtils.js @@ -2,8 +2,55 @@ const prisma = require('../config/db'); const { v4: uuidv4 } = require('uuid'); const { planLineTickets } = require('./attendees'); +/** Form fields that are only text to read (a statement, a heading). */ +const DISPLAY_FIELDS = ['statement', 'paragraph']; + +/** A required form with at least one question to answer — the only kind tickets wait for. */ +const formNeedsAnswers = (form) => !!(form && form.isRequired && (form.fields || []).some(f => !DISPLAY_FIELDS.includes(f.type))); + /** - * Generate tickets for a registration when payment status is "paid". + * How many attendee forms a registration's places need: one per main-ticket place. A picked- + * session booking has a line per session for the same people, so it counts once (its biggest + * line), not once per session. + */ +function formPlaces(registrationOptions) { + let total = 0; + const picked = new Map(); + for (const ro of registrationOptions || []) { + if (!ro.eventOption?.isMainTicket) continue; + const qty = ro.quantity || 0; + if (!ro.sessionId) { total += qty; continue; } + const key = `${ro.eventOptionId}::${ro.variantId || ''}`; + picked.set(key, Math.max(picked.get(key) || 0, qty)); + } + for (const qty of picked.values()) total += qty; + return total; +} + +/** + * The attendee forms a registration still needs before its tickets can be issued: 0 when the + * event's form isn't required (or has no questions), when the form was left for later + * (`formWaivedAt`), or when enough are in. `registration` is an id or a record with + * registrationOptions[].eventOption. + */ +async function formsOutstanding(registration) { + try { + const reg = typeof registration === 'string' + ? await prisma.registration.findUnique({ where: { id: registration }, include: { registrationOptions: { include: { eventOption: true } } } }) + : registration; + if (!reg || reg.formWaivedAt) return 0; + const form = await prisma.eventForm.findUnique({ where: { eventId: reg.eventId }, include: { fields: true } }); + if (!formNeedsAnswers(form)) return 0; + const submitted = await prisma.formResponse.count({ where: { registrationId: reg.id } }); + return Math.max(0, formPlaces(reg.registrationOptions) - submitted); + } catch (_) { + return 0; // form models unavailable — don't block + } +} + +/** + * Generate tickets for a registration when payment status is "paid" (or an admin released + * them unpaid) and no required attendee form is outstanding (see formsOutstanding). * * Rules: * - Each named attendee (group tickets) gets their own quantity-1 ticket; the rest of a @@ -34,19 +81,11 @@ const generateTicketsForRegistration = async (registrationId) => { }); if (!registration) throw new Error('Registration not found'); - if (registration.status !== 'paid') return []; + // Paid, or an admin issued the tickets before payment ("pay later", 1.52.0). + if (registration.status !== 'paid' && !(registration.ticketsReleasedAt && registration.status !== 'cancelled')) return []; - // If event has a required form, ensure sufficient responses exist - try { - const form = await prisma.eventForm.findUnique({ where: { eventId: registration.eventId } }); - if (form && form.isRequired) { - const requiredCount = (registration.registrationOptions || []) - .filter(ro => ro.eventOption?.isMainTicket) - .reduce((s, ro) => s + (ro.quantity || 0), 0); - const responsesCount = await prisma.formResponse.count({ where: { registrationId } }); - if (responsesCount < requiredCount) return []; - } - } catch (_) { /* form models unavailable — don't block */ } + // A required attendee form comes first, unless it's been left for later. + if ((await formsOutstanding(registration)) > 0) return []; // ── Step 1: Consolidate duplicate registrationOptions for the same (eventOptionId, variantId, session) ── // Key on both fields so that different variants of the same option are never merged @@ -133,4 +172,4 @@ const generateTicketsForRegistration = async (registrationId) => { } }; -module.exports = { generateTicketsForRegistration }; \ No newline at end of file +module.exports = { generateTicketsForRegistration, formsOutstanding, formPlaces, formNeedsAnswers, DISPLAY_FIELDS }; \ No newline at end of file diff --git a/apps/events/backend/src/v2/docs.ts b/apps/events/backend/src/v2/docs.ts new file mode 100644 index 0000000..9b1b3ed --- /dev/null +++ b/apps/events/backend/src/v2/docs.ts @@ -0,0 +1,210 @@ +/** + * Shapes for the API documentation (1.52.1): the records v1 handlers answer with, and the bodies + * they take, described once so every route shows the same thing the same way. Used as + * `documented: { body, response }` on v1Route (see RouteDef.documented) — shown in the OpenAPI + * document, not enforced; outside production anything that doesn't fit is logged. + * + * Everything is a loose object (extra fields pass, as v1 answers carry their Prisma includes), + * dates are ISO strings (as they arrive in JSON), and fields a handler may leave out are optional. + */ +import { z } from 'zod'; + +export const obj = (shape: T) => z.looseObject(shape); +export const str = z.string(); +export const optStr = z.string().nullish(); +export const num = z.number(); +export const optNum = z.number().nullish(); +export const bool = z.boolean(); +export const optBool = z.boolean().nullish(); +export const date = z.string().describe('Date and time (ISO 8601)'); +export const optDate = date.nullish(); +export const rand = z.number().describe('Rand'); +export const optRand = rand.nullish(); +export const anyObj = z.looseObject({}); +/** A number sent as a number or as text (forms send text). */ +export const numeric = z.union([z.number(), z.string()]); +export const ids = z.array(z.string()).describe('Ids'); +export const channel = z.enum(['email', 'whatsapp', 'both']).describe('How to send it'); + +/** `{ message }`: what was done, in words for the person. */ +export const message = obj({ message: str }); +/** `{ ok: true }` */ +export const ok = obj({ ok: z.literal(true) }); +/** v1's paged lists: `{ data, total, page, limit, pages }`. */ +export const v1Page = (item: T) => obj({ data: z.array(item), total: num, page: num, limit: num, pages: num }); +/** A `{ redirectUrl }` answer from a checkout: where to send the person to pay. */ +export const checkout = obj({ + checkoutId: optStr, + redirectUrl: optStr.describe('Where to send the person to pay (null when the provider takes a form)'), + provider: optStr, + form: obj({ action: str, fields: z.record(z.string(), z.string()) }).nullish().describe('A form to post (PayFast)'), +}); + +export const userSummary = obj({ id: str.optional(), name: str, email: optStr, phoneNumber: optStr }); +export const userRef = obj({ id: str.optional(), name: str, email: optStr }); + +export const user = obj({ + id: str, + name: str, + email: str, + phoneNumber: optStr, + role: z.enum(['admin', 'supervisor', 'staff', 'user']), + isActive: optBool, + notificationPreference: z.enum(['email', 'whatsapp', 'both']).nullish(), + homeCampusId: optStr, + createdAt: optDate, +}); + +export const eventRef = obj({ id: str, title: str, startDate: optDate, endDate: optDate }); + +export const event = obj({ + id: str, + title: str, + description: optStr, + startDate: date, + endDate: date, + location: optStr, + price: optRand, + isActive: optBool, + isHidden: optBool, + imageUrl: optStr, + campusId: optStr, + scheduleType: z.enum(['single', 'sessions']).nullish(), + cashupStatus: z.enum(['open', 'closed']).nullish(), +}); + +export const session = obj({ id: str, label: optStr, startsAt: date, endsAt: date, cancelledAt: optDate, capacity: optNum }); + +export const eventOption = obj({ + id: str, + eventId: str.optional(), + name: str, + description: optStr, + price: rand, + isMainTicket: bool, + stockLimit: optNum, +}); + +export const payment = obj({ + id: str, + amount: rand.describe('Rand; a refund is negative'), + method: str.describe('cash, card, eft, other — or the wallet type for an online payment'), + provider: optStr.describe('yoco or payfast for an online payment'), + userId: str, + recordedById: optStr, + registrationId: optStr, + eventId: optStr, + isDonation: bool, + isSponsorship: optBool, + originalPaymentId: optStr.describe('A refund: the payment it refunds; a donation leg: the donation'), + externalId: optStr, + createdAt: date, + user: userSummary.nullish(), + recordedBy: userRef.nullish(), + event: eventRef.nullish(), +}); + +export const registrationStatus = z.enum(['pending', 'confirmed', 'partial_paid', 'paid', 'cancelled']); + +export const registration = obj({ + id: str, + userId: str, + eventId: str, + status: registrationStatus, + discountTotal: optRand, + totalDueComputed: optRand.describe('What it costs now, after discounts'), + createdAt: date, + user: userSummary.nullish(), + event: eventRef.nullish(), +}); + +export const ticket = obj({ + id: str, + qrCode: str.describe('What the QR code holds'), + quantity: num.describe('People on the ticket'), + isUsed: bool, + eventId: str, + userId: str.describe('The payer'), + registrationOptionId: str, + attendeeId: optStr.describe('A named ticket: the person it\'s for'), + holderUserId: optStr, + createdAt: date, +}); + +export const auditEntry = obj({ + id: str, + action: str, + actorRole: optStr, + targetType: optStr, + targetId: optStr, + metadata: anyObj.nullish(), + ip: optStr, + createdAt: date, + actor: userRef.nullish(), +}); + +/** + * What the common query parameters mean, for routes that declare them by name only (`filters(…)` + * in the resource files). The OpenAPI document uses these when a parameter has no description. + */ +export const QUERY_HELP: Record = { + page: 'Page number, from 1', + limit: 'How many per page', + eventId: 'Only this event', + eventIds: 'These events (comma-separated ids)', + registrationId: 'Only this registration', + userId: 'Only this person', + actorId: 'Only things this person did', + sessionId: 'Multi-day events: the session (default: today\'s)', + deviceId: 'This device\'s id (offline scanning)', + from: 'On or after (ISO date or date-time)', + to: 'On or before (ISO date or date-time)', + startDate: 'On or after (ISO date)', + endDate: 'On or before (ISO date)', + before: 'Older than (ISO date-time), for the next page', + cursor: 'Where the last page ended (its `nextCursor`)', + search: 'Text to search for', + q: 'Text to search for', + status: 'Only this status', + role: 'admin, supervisor, staff or user', + isActive: '`true` or `false`', + campus: 'Campus id or slug (`all` for every campus)', + series: 'Event series slug', + format: 'File type, e.g. `pdf` or `xlsx`', + log: '`1` also writes it to the access log (a list with personal details)', + all: '`true`/`1`: include everything, not just the current ones', + medical: '`true`: include medical notes (supervisors; logged)', + type: 'Which kind', + action: 'Only this action', + sensitive: '`true`: only access to sensitive information', + version: 'A version number (default: the current one)', + provider: 'yoco or payfast', + method: 'Payment method: cash, card, eft, other', + kind: 'payment or refund', + donations: '`1`: only donations and the parts put towards registrations', + channel: 'email or whatsapp', + email: 'An email address', + phone: 'A phone number', + phoneNumber: 'A phone number', + past: '`true`: include ones that are over too', + unpaid: '`true`: only ones with money still owed', + unreviewed: '`true`: only the ones not reviewed yet', + seriesId: 'Only this event series', + registrants: '`true`: also people registered for its events in the last 12 months', +}; + +/** What path parameters are, when the route doesn't say. */ +export const PATH_HELP: Record = { + id: 'The id', + userId: 'The person\'s id', + attendeeId: 'The named attendee\'s id', + attachmentId: 'The attachment\'s id', + familyId: 'The family\'s id', + childId: 'The child\'s id', + slug: 'The short name in the address', + token: 'The token from the link (it is the credential)', + qrCode: 'What the ticket\'s QR code holds', + code: 'The code', + name: 'The name', + filename: 'The file name', +}; diff --git a/apps/events/backend/src/v2/index.ts b/apps/events/backend/src/v2/index.ts index b88735e..e5e51ac 100644 --- a/apps/events/backend/src/v2/index.ts +++ b/apps/events/backend/src/v2/index.ts @@ -16,6 +16,7 @@ import './resources/registrations'; import './resources/registrationsManage'; import './resources/money'; import './resources/attendance'; +import './resources/corrections'; import './resources/kidsVolunteers'; import './resources/peopleMessaging'; import './resources/adminPrivacy'; diff --git a/apps/events/backend/src/v2/openapi.ts b/apps/events/backend/src/v2/openapi.ts index abd686b..0686e34 100644 --- a/apps/events/backend/src/v2/openapi.ts +++ b/apps/events/backend/src/v2/openapi.ts @@ -1,6 +1,7 @@ import { z } from 'zod'; import { routes as allRoutes, type AnyRoute, type Access } from './route'; import { ERROR_STATUS } from './errors'; +import { PATH_HELP, QUERY_HELP } from './docs'; /** * The OpenAPI 3.1 document for /api/v2, built from the route declarations (route.ts), so it is @@ -48,7 +49,8 @@ function parameters(def: AnyRoute) { if (!schema) return; const json = toSchema(schema, 'input') as { properties?: Record; required?: string[] }; for (const [name, prop] of Object.entries(json.properties || {})) { - const { description, ...propSchema } = prop as JsonSchema & { description?: string }; + const { description: own, ...propSchema } = prop as JsonSchema & { description?: string }; + const description = own || (where === 'query' ? QUERY_HELP[name] : PATH_HELP[name]); out.push({ name, in: where, required: where === 'path' || (json.required || []).includes(name), ...(description ? { description } : {}), schema: propSchema }); } }; @@ -57,6 +59,14 @@ function parameters(def: AnyRoute) { return out; } +/** A JSON body; one with nothing in it (an action that takes no input) says so. */ +function requestBody(schema: JsonSchema) { + const empty = !(schema as { properties?: object }).properties || !Object.keys((schema as { properties: object }).properties).length; + return empty + ? { required: true, description: 'No body needed: send an empty object.', content: { 'application/json': { schema } } } + : { required: true, content: { 'application/json': { schema } } }; +} + export function buildOpenApi(opts: { version: string; serverUrl?: string; list?: AnyRoute[] }) { const list = opts.list ?? allRoutes; const paths: Record> = {}; @@ -73,11 +83,11 @@ export function buildOpenApi(opts: { version: string; serverUrl?: string; list?: 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') } } } } : {}), + : (def.documented?.body || def.body) ? { requestBody: requestBody(toSchema((def.documented?.body || 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') } } }, + : { description: 'OK', content: { 'application/json': { schema: toSchema(def.documented?.response ? z.object({ data: def.documented.response }) : 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)') } : {}), diff --git a/apps/events/backend/src/v2/resources/adminPrivacy.ts b/apps/events/backend/src/v2/resources/adminPrivacy.ts index 59aed3e..98abdf6 100644 --- a/apps/events/backend/src/v2/resources/adminPrivacy.ts +++ b/apps/events/backend/src/v2/resources/adminPrivacy.ts @@ -8,6 +8,7 @@ import { z } from 'zod'; import { idParams } from '../schemas'; import { v1Route } from '../viaV1'; +import * as D from '../docs'; /* eslint-disable @typescript-eslint/no-explicit-any -- v1 handlers and middleware are JavaScript */ const rateLimit = require('express-rate-limit') as (opts: object) => any; @@ -26,101 +27,136 @@ const filters = (...names: string[]) => z.looseObject(Object.fromEntries(names.m const tokenParams = z.object({ token: z.string().min(1).max(500) }); const exportLimiter = rateLimit({ windowMs: 10 * 60 * 1000, max: 10, standardHeaders: true, legacyHeaders: false }); +// ─── Documented shapes (docs.ts) ───────────────────────────────────────────── + +const news = D.obj({ email: D.bool, whatsapp: D.bool }); +const dataRequest = D.obj({ + id: D.str, type: z.enum(['access', 'correction', 'deletion']), status: z.enum(['open', 'completed', 'rejected', 'cancelled']), + userId: D.optStr, name: D.str.optional(), email: D.str.optional(), details: D.optStr, response: D.optStr, dueAt: D.optDate.describe('30 days after it was made'), + closedAt: D.optDate, createdAt: D.date, +}); +const noticeSection = D.obj({ key: D.str.optional(), title: D.str, body: D.str.describe('Text; {placeholders} are filled in') }); +const operatorInput = D.obj({ name: D.str, purpose: D.str.describe('What they do for the church'), dataShared: D.optStr, location: D.optStr.describe('Country the data is kept in'), website: D.optStr, active: D.optBool, order: D.optNum }); +const operator = operatorInput.extend({ id: D.str, active: D.bool, order: D.num, createdAt: D.date, updatedAt: D.date }); +const logPage = (row: T) => D.obj({ total: D.num, pageSize: D.num, rows: z.array(row) }); +const breachInput = D.obj({ + title: D.str, description: D.str, dataAffected: D.str, peopleAffected: D.numeric.nullish(), whoAffected: D.optStr, consequences: D.optStr, + actionsTaken: D.optStr, adviceToPeople: D.optStr, causedBy: D.optStr, status: D.optStr.describe('open or closed'), + discoveredAt: D.date, occurredAt: D.optDate, regulatorNotifiedAt: D.optDate.describe('When the Information Regulator was told'), peopleNotifiedAt: D.optDate, +}); +const breach = breachInput.extend({ id: D.str, status: D.str, createdAt: D.date, updatedAt: D.date, createdBy: D.obj({ name: D.str }).nullish() }); +const retentionState = D.obj({ + policies: D.anyObj.describe('Per kind of information: how long it is kept'), definitions: D.anyObj, preview: D.anyObj.describe('What the rules would remove now'), + lastRun: D.anyObj.nullish(), related: D.obj({ medicalDays: D.num, backupCount: D.num, analyticsDays: D.num }), +}); +const hubStatus = D.obj({ + state: D.str.describe('active, grace, suspended, revoked, none…'), readOnly: D.bool, daysLeft: D.optNum, endsAt: D.optDate, graceEndsAt: D.optDate, + licence: D.obj({ customer: D.optStr, plan: D.optStr, status: D.optStr, licenceExpiresAt: D.optDate, graceDays: D.optNum, issuedAt: D.optDate, validUntil: D.optDate, limits: D.anyObj }).nullish(), + connected: D.bool, keyConfigured: D.bool, hubUrl: D.optStr, lastHeartbeatAt: D.optDate, lastError: D.optStr, + version: D.str.describe('This site\'s version'), latestVersion: D.optStr, updateAvailable: D.bool, urgentUpdate: D.bool, updateSnoozed: D.optBool, + releases: z.array(D.anyObj).optional().describe('What\'s new in each version since this one'), updateRequest: D.anyObj.nullish(), notices: z.array(D.anyObj).optional(), +}); +const webhook = D.obj({ + id: D.str, name: D.str, url: D.str, events: z.array(D.str).describe('Event types it gets'), isActive: D.bool, operatorId: D.optStr.describe('Its entry in the operator register'), + lastSuccessAt: D.optDate, lastFailureAt: D.optDate, createdAt: D.date, +}); +const delivered = D.obj({ status: D.optStr.describe('succeeded, failed, retrying…'), statusCode: D.optNum, error: D.optStr }); + // ─── My privacy ────────────────────────────────────────────────────────────── -v1Route({ method: 'get', path: '/me/privacy', tag: 'Privacy', summary: 'My privacy settings', description: 'News consent, open requests, and whether there\'s a privacy notice to accept.', access: 'user', v1: privacy.getMyPrivacy }); -v1Route({ method: 'put', path: '/me/privacy/news', tag: 'Privacy', summary: 'Choose whether to get news', access: 'user', body: loose, v1: privacy.updateMyNews }); +v1Route({ method: 'get', path: '/me/privacy', tag: 'Privacy', summary: 'My privacy settings', description: 'News consent, open requests, and whether there\'s a privacy notice to accept.', access: 'user', documented: { response: D.obj({ news, newsAskedAt: D.optDate, canWhatsApp: D.bool, notificationPreference: D.optStr, history: z.array(D.anyObj).describe('Every change to my news consent'), requests: z.array(dataRequest) }) }, v1: privacy.getMyPrivacy }); +v1Route({ method: 'put', path: '/me/privacy/news', tag: 'Privacy', summary: 'Choose whether to get news', access: 'user', body: loose, documented: { body: D.obj({ email: D.optBool, whatsapp: D.optBool, source: D.optStr.describe('Where it was changed, for the consent log') }), response: D.obj({ news, newsAskedAt: D.optDate }) }, v1: privacy.updateMyNews }); v1Route({ method: 'get', path: '/me/privacy/export', tag: 'Privacy', summary: 'Download everything held about me', description: '`format=pdf` or JSON (the default).', access: 'user', middleware: [exportLimiter], query: filters('format'), file: { contentType: 'application/json' }, v1: privacy.exportMyData }); -v1Route({ method: 'post', path: '/me/privacy/requests', tag: 'Privacy', summary: 'Ask for my data to be corrected or deleted', access: 'user', status: 201, body: loose, v1: privacy.createMyRequest }); -v1Route({ method: 'post', path: '/me/privacy/notice/accept', tag: 'Privacy', summary: 'Accept the privacy notice', access: 'user', body: loose, v1: privacy.acceptMyNotice }); -v1Route({ method: 'get', path: '/privacy/notice', tag: 'Privacy', summary: 'The published privacy notice', access: 'public', query: filters('version'), v1: privacy.getNotice }); -v1Route({ method: 'get', path: '/unsubscribe/:token', tag: 'Privacy', summary: 'What an unsubscribe link is for', description: 'The token in the link is the credential.', access: 'public', params: tokenParams, v1: privacy.getUnsubscribe }); -v1Route({ method: 'post', path: '/unsubscribe/:token', tag: 'Privacy', summary: 'Unsubscribe with a link', access: 'public', params: tokenParams, body: loose, v1: privacy.postUnsubscribe }); +v1Route({ method: 'post', path: '/me/privacy/requests', tag: 'Privacy', summary: 'Ask for my data to be corrected or deleted', access: 'user', status: 201, body: loose, documented: { body: D.obj({ type: z.enum(['correction', 'deletion']), details: D.optStr.describe('A correction: what to change'), password: D.optStr.describe('A deletion: closes the account too') }), response: D.obj({ request: dataRequest, message: D.str }) }, v1: privacy.createMyRequest }); +v1Route({ method: 'post', path: '/me/privacy/notice/accept', tag: 'Privacy', summary: 'Accept the privacy notice', access: 'user', body: loose, documented: { response: D.obj({ version: D.num.describe('The version accepted') }) }, v1: privacy.acceptMyNotice }); +v1Route({ method: 'get', path: '/privacy/notice', tag: 'Privacy', summary: 'The published privacy notice', access: 'public', query: filters('version'), documented: { response: D.obj({ version: D.num.describe('0: the built-in text'), builtIn: D.optBool, current: D.optBool, publishedAt: D.optDate, effectiveDate: D.optStr, changeSummary: D.optStr, sections: z.array(D.anyObj).describe('Rendered sections'), versions: z.array(D.anyObj).describe('Every published version') }) }, v1: privacy.getNotice }); +v1Route({ method: 'get', path: '/unsubscribe/:token', tag: 'Privacy', summary: 'What an unsubscribe link is for', description: 'The token in the link is the credential.', access: 'public', params: tokenParams, documented: { response: D.obj({ kind: z.enum(['account', 'address']), email: D.optStr.describe('Partly hidden'), hasPhone: D.optBool, news: D.obj({ email: D.bool, whatsapp: D.bool }).optional(), address: D.optStr.describe('kind address: the email or phone, partly hidden') }) }, v1: privacy.getUnsubscribe }); +v1Route({ method: 'post', path: '/unsubscribe/:token', tag: 'Privacy', summary: 'Unsubscribe with a link', access: 'public', params: tokenParams, body: loose, documented: { body: D.obj({ channels: z.array(z.enum(['email', 'whatsapp'])).optional().describe('Default: the link\'s channel') }), response: D.message }, v1: privacy.postUnsubscribe }); // ─── Privacy admin ─────────────────────────────────────────────────────────── -v1Route({ method: 'get', path: '/privacy/requests', tag: 'Privacy', summary: 'Data requests', description: '`status=open` (default), `closed` or `all`.', access: 'admin', query: filters('status', 'search', 'page', 'limit'), v1: privacy.listRequests }); -v1Route({ method: 'post', path: '/privacy/requests/:id/complete', tag: 'Privacy', summary: 'Mark a data request done', access: 'admin', params: idParams, body: loose, v1: privacy.completeRequest }); -v1Route({ method: 'post', path: '/privacy/requests/:id/reject', tag: 'Privacy', summary: 'Turn down a data request', access: 'admin', params: idParams, body: loose, v1: privacy.rejectRequest }); -v1Route({ method: 'get', path: '/privacy/notice/draft', tag: 'Privacy', summary: 'The privacy notice being drafted', access: 'admin', v1: privacy.getNoticeDraft }); -v1Route({ method: 'put', path: '/privacy/notice/draft', tag: 'Privacy', summary: 'Save the draft notice', access: 'admin', body: loose, v1: privacy.saveNoticeDraft }); -v1Route({ method: 'delete', path: '/privacy/notice/draft', tag: 'Privacy', summary: 'Throw the draft away', access: 'admin', v1: privacy.discardNoticeDraft }); -v1Route({ method: 'post', path: '/privacy/notice/publish', tag: 'Privacy', summary: 'Publish the draft notice', description: 'Everyone is asked to accept it at their next sign-in.', access: 'admin', body: loose, v1: privacy.publishNotice }); -v1Route({ method: 'post', path: '/privacy/notice/builtin-reviewed', tag: 'Privacy', summary: 'Mark the built-in notice as reviewed', access: 'admin', body: loose, v1: privacy.markBuiltInReviewed }); -v1Route({ method: 'get', path: '/privacy/operators', tag: 'Privacy', summary: 'Who processes personal information for the church', access: 'admin', v1: privacy.listOperators }); -v1Route({ method: 'post', path: '/privacy/operators', tag: 'Privacy', summary: 'Add an operator', access: 'admin', status: 201, body: loose, v1: privacy.createOperator }); -v1Route({ method: 'put', path: '/privacy/operators/:id', tag: 'Privacy', summary: 'Change an operator', access: 'admin', params: idParams, body: loose, v1: privacy.updateOperator }); -v1Route({ method: 'delete', path: '/privacy/operators/:id', tag: 'Privacy', summary: 'Remove an operator', access: 'admin', params: idParams, v1: privacy.deleteOperator }); -v1Route({ method: 'get', path: '/privacy/consent-log', tag: 'Privacy', summary: 'Consent given and withdrawn', access: 'admin', query: filters('type', 'page', 'q'), v1: privacy.consentLog }); -v1Route({ method: 'get', path: '/privacy/access-log', tag: 'Privacy', summary: 'Who looked at sensitive information', access: 'admin', query: filters('page', 'action', 'sensitive', 'actorId', 'from', 'to'), v1: privacy.accessLog }); -v1Route({ method: 'get', path: '/privacy/readiness', tag: 'Privacy', summary: 'POPIA checklist', access: 'admin', v1: privacy.getReadiness }); -v1Route({ method: 'get', path: '/privacy/retention', tag: 'Privacy', summary: 'How long information is kept', access: 'admin', v1: privacy.getRetention }); -v1Route({ method: 'put', path: '/privacy/retention', tag: 'Privacy', summary: 'Change how long information is kept', access: 'admin', body: loose, v1: privacy.saveRetention }); -v1Route({ method: 'post', path: '/privacy/retention/run', tag: 'Privacy', summary: 'Apply the retention rules now', access: 'admin', body: loose, v1: privacy.runRetentionNow }); -v1Route({ method: 'get', path: '/privacy/breaches', tag: 'Privacy', summary: 'Recorded data breaches', access: 'admin', v1: privacy.listBreaches }); -v1Route({ method: 'post', path: '/privacy/breaches', tag: 'Privacy', summary: 'Record a data breach', access: 'admin', status: 201, body: loose, v1: privacy.createBreach }); -v1Route({ method: 'put', path: '/privacy/breaches/:id', tag: 'Privacy', summary: 'Update a data breach', access: 'admin', params: idParams, body: loose, v1: privacy.updateBreach }); +v1Route({ method: 'get', path: '/privacy/requests', tag: 'Privacy', summary: 'Data requests', description: '`status=open` (default), `closed` or `all`.', access: 'admin', query: filters('status', 'search', 'page', 'limit'), documented: { response: D.obj({ requests: z.array(dataRequest.extend({ overdue: D.optBool, blockers: z.array(D.anyObj).optional().describe('Upcoming registrations that stop a deletion') })), openCount: D.num, total: D.num, page: D.num, limit: D.num, pages: D.num }) }, v1: privacy.listRequests }); +v1Route({ method: 'post', path: '/privacy/requests/:id/complete', tag: 'Privacy', summary: 'Mark a data request done', access: 'admin', params: idParams, body: loose, documented: { body: D.obj({ response: D.optStr.describe('Emailed to them; needed for a correction') }), response: D.obj({ request: dataRequest, anonymised: D.anyObj.nullish().describe('A deletion: what was removed') }) }, v1: privacy.completeRequest }); +v1Route({ method: 'post', path: '/privacy/requests/:id/reject', tag: 'Privacy', summary: 'Turn down a data request', access: 'admin', params: idParams, body: loose, documented: { body: D.obj({ response: D.str.describe('The reason, emailed to them'), cancelled: D.optBool.describe('They withdrew it') }), response: D.obj({ request: dataRequest }) }, v1: privacy.rejectRequest }); +v1Route({ method: 'get', path: '/privacy/notice/draft', tag: 'Privacy', summary: 'The privacy notice being drafted', access: 'admin', documented: { response: D.obj({ sections: z.array(noticeSection), isDraft: D.optBool, rendered: z.array(D.anyObj).describe('The sections with placeholders filled in'), placeholders: z.array(D.str).describe('The placeholders the text can use'), versions: z.array(D.anyObj).describe('Published versions'), builtIn: z.array(noticeSection), builtInUpdates: z.array(D.anyObj).describe('Changes to the built-in text not reviewed yet') }) }, v1: privacy.getNoticeDraft }); +v1Route({ method: 'put', path: '/privacy/notice/draft', tag: 'Privacy', summary: 'Save the draft notice', access: 'admin', body: loose, documented: { body: D.obj({ sections: z.array(noticeSection) }), response: D.obj({ sections: z.array(noticeSection), rendered: z.array(D.anyObj), isDraft: z.literal(true), savedAt: D.date }) }, v1: privacy.saveNoticeDraft }); +v1Route({ method: 'delete', path: '/privacy/notice/draft', tag: 'Privacy', summary: 'Throw the draft away', access: 'admin', documented: { response: D.message }, v1: privacy.discardNoticeDraft }); +v1Route({ method: 'post', path: '/privacy/notice/publish', tag: 'Privacy', summary: 'Publish the draft notice', description: 'Everyone is asked to accept it at their next sign-in.', access: 'admin', body: loose, documented: { body: D.obj({ sections: z.array(noticeSection).optional(), changeSummary: D.str.describe('Shown to people asked to accept it'), requiresAcceptance: D.optBool }), response: D.obj({ version: D.num, publishedAt: D.date, requiresAcceptance: D.bool }) }, v1: privacy.publishNotice }); +v1Route({ method: 'post', path: '/privacy/notice/builtin-reviewed', tag: 'Privacy', summary: 'Mark the built-in notice as reviewed', access: 'admin', body: loose, documented: { response: D.obj({ builtInUpdates: z.array(D.anyObj) }) }, v1: privacy.markBuiltInReviewed }); +v1Route({ method: 'get', path: '/privacy/operators', tag: 'Privacy', summary: 'Who processes personal information for the church', access: 'admin', documented: { response: z.array(operator) }, v1: privacy.listOperators }); +v1Route({ method: 'post', path: '/privacy/operators', tag: 'Privacy', summary: 'Add an operator', access: 'admin', status: 201, body: loose, documented: { body: operatorInput, response: operator }, v1: privacy.createOperator }); +v1Route({ method: 'put', path: '/privacy/operators/:id', tag: 'Privacy', summary: 'Change an operator', access: 'admin', params: idParams, body: loose, documented: { body: operatorInput.partial(), response: operator }, v1: privacy.updateOperator }); +v1Route({ method: 'delete', path: '/privacy/operators/:id', tag: 'Privacy', summary: 'Remove an operator', access: 'admin', params: idParams, documented: { response: D.message }, v1: privacy.deleteOperator }); +v1Route({ method: 'get', path: '/privacy/consent-log', tag: 'Privacy', summary: 'Consent given and withdrawn', access: 'admin', query: filters('type', 'page', 'q'), documented: { response: logPage(D.obj({ id: D.str, at: D.optDate, name: D.optStr })).describe('`type` news: email, channel, granted, source, ip; notice: email, version, source, ip; parental: child, event, status, signedName') }, v1: privacy.consentLog }); +v1Route({ method: 'get', path: '/privacy/access-log', tag: 'Privacy', summary: 'Who looked at sensitive information', access: 'admin', query: filters('page', 'action', 'sensitive', 'actorId', 'from', 'to'), documented: { response: logPage(D.obj({ id: D.str, at: D.date, actor: D.str, actorRole: D.optStr, action: D.str, what: D.optStr, records: D.optNum, eventId: D.optStr, ip: D.optStr, sensitive: D.bool })).extend({ actions: z.array(D.str), actors: z.array(D.obj({ id: D.str, name: D.str })) }) }, v1: privacy.accessLog }); +v1Route({ method: 'get', path: '/privacy/readiness', tag: 'Privacy', summary: 'POPIA checklist', access: 'admin', documented: { response: D.obj({ score: D.num.describe('%'), passed: D.num, total: D.num, checks: z.array(D.obj({ key: D.str, label: D.str, ok: D.bool, detail: D.optStr, href: D.optStr, applies: D.bool })) }) }, v1: privacy.getReadiness }); +v1Route({ method: 'get', path: '/privacy/retention', tag: 'Privacy', summary: 'How long information is kept', access: 'admin', documented: { response: retentionState }, v1: privacy.getRetention }); +v1Route({ method: 'put', path: '/privacy/retention', tag: 'Privacy', summary: 'Change how long information is kept', access: 'admin', body: loose, documented: { body: D.obj({ policies: D.anyObj.describe('Per kind of information: { enabled, months }') }), response: retentionState }, v1: privacy.saveRetention }); +v1Route({ method: 'post', path: '/privacy/retention/run', tag: 'Privacy', summary: 'Apply the retention rules now', access: 'admin', body: loose, documented: { response: D.obj({ result: D.anyObj.describe('What was removed or anonymised'), state: retentionState }) }, v1: privacy.runRetentionNow }); +v1Route({ method: 'get', path: '/privacy/breaches', tag: 'Privacy', summary: 'Recorded data breaches', access: 'admin', documented: { response: z.array(breach) }, v1: privacy.listBreaches }); +v1Route({ method: 'post', path: '/privacy/breaches', tag: 'Privacy', summary: 'Record a data breach', access: 'admin', status: 201, body: loose, documented: { body: breachInput, response: breach }, v1: privacy.createBreach }); +v1Route({ method: 'put', path: '/privacy/breaches/:id', tag: 'Privacy', summary: 'Update a data breach', access: 'admin', params: idParams, body: loose, documented: { body: breachInput.partial(), response: breach }, v1: privacy.updateBreach }); // ─── Admin ─────────────────────────────────────────────────────────────────── -v1Route({ method: 'get', path: '/admin/audit-log', tag: 'Admin', summary: 'The audit log', access: 'admin', query: filters('page', 'limit', 'actorId', 'action', 'role', 'from', 'to', 'search'), v1: audit.listAuditLog }); -v1Route({ method: 'get', path: '/admin/jobs', tag: 'Admin', summary: 'Background jobs', access: 'admin', v1: jobs.listJobs }); -v1Route({ method: 'post', path: '/admin/jobs/:name/run', tag: 'Admin', summary: 'Run a background job now', access: 'admin', params: z.object({ name: z.string().min(1).max(100) }), body: loose, v1: jobs.runJobNow }); -v1Route({ method: 'get', path: '/admin/impersonation-sessions', tag: 'Admin', summary: 'Times admins viewed the site as someone else', access: 'admin', query: filters('limit'), v1: imp.listSessions }); -v1Route({ method: 'post', path: '/admin/impersonate/:userId', tag: 'Admin', summary: 'View the site as someone (read-only)', description: 'Answers a token for a read-only session, logged.', access: 'admin', params: z.object({ userId: z.string().min(1).max(64) }), body: loose, v1: imp.startImpersonation }); -v1Route({ method: 'get', path: '/me/impersonation', tag: 'Admin', summary: 'The viewing-as session I\'m in, if any', access: 'user', v1: imp.currentImpersonation }); -v1Route({ method: 'post', path: '/me/impersonation/end', tag: 'Admin', summary: 'Stop viewing as someone', access: 'user', body: loose, v1: imp.endImpersonation }); -v1Route({ method: 'post', path: '/me/impersonation/log', tag: 'Admin', summary: 'Record a page viewed while viewing as someone', access: 'user', body: loose, v1: imp.logPageView }); +v1Route({ method: 'get', path: '/admin/audit-log', tag: 'Admin', summary: 'The audit log', access: 'admin', query: filters('page', 'limit', 'actorId', 'action', 'role', 'from', 'to', 'search'), documented: { response: D.obj({ rows: z.array(D.auditEntry), total: D.num, page: D.num, limit: D.num }) }, v1: audit.listAuditLog }); +v1Route({ method: 'get', path: '/admin/jobs', tag: 'Admin', summary: 'Background jobs', access: 'admin', documented: { response: D.obj({ mode: D.str.describe('on, off or timers'), timezone: D.str, jobs: z.array(D.obj({ name: D.str, label: D.str, cron: D.optStr, enabled: D.bool, envFlag: D.optStr, nextRun: D.optDate, recent: z.array(D.anyObj).describe('Recent runs') })) }) }, v1: jobs.listJobs }); +v1Route({ method: 'post', path: '/admin/jobs/:name/run', tag: 'Admin', summary: 'Run a background job now', access: 'admin', params: z.object({ name: z.string().min(1).max(100) }), body: loose, documented: { response: D.obj({ queued: D.bool, id: D.optStr, output: z.unknown().optional().describe('When it ran straight away') }) }, v1: jobs.runJobNow }); +v1Route({ method: 'get', path: '/admin/impersonation-sessions', tag: 'Admin', summary: 'Times admins viewed the site as someone else', access: 'admin', query: filters('limit'), documented: { response: z.array(D.obj({ id: D.str, reason: D.optStr, startedAt: D.optDate, endedAt: D.optDate, expiresAt: D.optDate, admin: D.obj({ name: D.str, email: D.optStr }).nullish(), target: D.obj({ name: D.str, email: D.optStr }).nullish(), requests: z.array(D.obj({ method: D.str, path: D.str, blocked: D.bool, createdAt: D.date })).describe('What they did (up to 500)') })) }, v1: imp.listSessions }); +v1Route({ method: 'post', path: '/admin/impersonate/:userId', tag: 'Admin', summary: 'View the site as someone (read-only)', description: 'Answers a token for a read-only session, logged.', access: 'admin', params: z.object({ userId: z.string().min(1).max(64) }), body: loose, documented: { body: D.obj({ reason: D.str.describe('Why — kept in the log') }), response: D.obj({ token: D.str.describe('A read-only sign-in token'), session: D.obj({ id: D.str, expiresAt: D.date, target: D.obj({ id: D.str, name: D.str, email: D.str, role: D.str }) }) }) }, v1: imp.startImpersonation }); +v1Route({ method: 'get', path: '/me/impersonation', tag: 'Admin', summary: 'The viewing-as session I\'m in, if any', access: 'user', documented: { response: D.obj({ id: D.str, expiresAt: D.date, target: D.userRef }).nullable() }, v1: imp.currentImpersonation }); +v1Route({ method: 'post', path: '/me/impersonation/end', tag: 'Admin', summary: 'Stop viewing as someone', access: 'user', body: loose, documented: { response: D.message }, v1: imp.endImpersonation }); +v1Route({ method: 'post', path: '/me/impersonation/log', tag: 'Admin', summary: 'Record a page viewed while viewing as someone', access: 'user', body: loose, documented: { body: D.obj({ path: D.str }), response: z.null().describe('Always 204, no content') }, v1: imp.logPageView }); // ─── Settings and first-run set-up ─────────────────────────────────────────── -v1Route({ method: 'get', path: '/settings', tag: 'Site', summary: 'Public site settings', description: 'Name, branding, contact details and what\'s switched on.', access: 'public', v1: settings.getSettings }); -v1Route({ method: 'get', path: '/settings/all', tag: 'Site', summary: 'Every setting', description: 'Admins. Secrets are masked.', access: 'admin', v1: settings.getAllSettings }); -v1Route({ method: 'put', path: '/settings', tag: 'Site', summary: 'Change settings', access: 'admin', body: loose, v1: settings.updateSettings }); -v1Route({ method: 'post', path: '/settings/test-smtp', tag: 'Site', summary: 'Send a test email', access: 'admin', body: loose, v1: settings.testSmtp }); -v1Route({ method: 'get', path: '/setup/needed', tag: 'Site', summary: 'Does the site still need setting up?', access: 'public', v1: settings.needsSetup }); -v1Route({ method: 'post', path: '/setup/register', tag: 'Site', summary: 'Create the first admin', description: 'Only while no account exists.', access: 'public', body: loose, v1: settings.setupRegister }); -v1Route({ method: 'post', path: '/setup', tag: 'Site', summary: 'Finish first-run set-up', access: 'admin', body: loose, v1: settings.runSetup }); +v1Route({ method: 'get', path: '/settings', tag: 'Site', summary: 'Public site settings', description: 'Name, branding, contact details and what\'s switched on.', access: 'public', documented: { response: z.record(z.string(), z.string()).describe('Setting key → value: name, logo, colours, contact details, what\'s switched on') }, v1: settings.getSettings }); +v1Route({ method: 'get', path: '/settings/all', tag: 'Site', summary: 'Every setting', description: 'Admins. Secrets are masked.', access: 'admin', documented: { response: z.record(z.string(), z.unknown()).describe('Setting key → value; secrets masked') }, v1: settings.getAllSettings }); +v1Route({ method: 'put', path: '/settings', tag: 'Site', summary: 'Change settings', access: 'admin', body: loose, documented: { body: z.record(z.string(), z.unknown()).describe('Setting key → new value'), response: D.message }, v1: settings.updateSettings }); +v1Route({ method: 'post', path: '/settings/test-smtp', tag: 'Site', summary: 'Send a test email', access: 'admin', body: loose, documented: { body: D.obj({ host: D.optStr, port: D.numeric.optional(), secure: z.union([D.bool, D.str]).optional(), user: D.optStr, pass: D.optStr, from: D.optStr }).describe('Unsaved SMTP details to try (default: the saved ones)'), response: D.message }, v1: settings.testSmtp }); +v1Route({ method: 'get', path: '/setup/needed', tag: 'Site', summary: 'Does the site still need setting up?', access: 'public', documented: { response: D.obj({ needsSetup: D.bool }) }, v1: settings.needsSetup }); +v1Route({ method: 'post', path: '/setup/register', tag: 'Site', summary: 'Create the first admin', description: 'Only while no account exists.', access: 'public', body: loose, documented: { body: D.obj({ adminName: D.str, adminEmail: D.str, adminPassword: D.str.describe('At least 8 characters') }), response: D.obj({ token: D.str, name: D.str, email: D.str }) }, v1: settings.setupRegister }); +v1Route({ method: 'post', path: '/setup', tag: 'Site', summary: 'Finish first-run set-up', access: 'admin', body: loose, documented: { body: D.obj({ settings: z.record(z.string(), z.unknown()).describe('Setting key → value') }), response: D.message }, v1: settings.runSetup }); // ─── Hub ───────────────────────────────────────────────────────────────────── -v1Route({ method: 'get', path: '/hub/status', tag: 'Site', summary: 'The connection to the provider\'s Hub', access: 'admin', v1: hub.getStatus }); -v1Route({ method: 'post', path: '/hub/connect', tag: 'Site', summary: 'Connect to the Hub', access: 'admin', body: loose, v1: hub.connect }); -v1Route({ method: 'post', path: '/hub/heartbeat', tag: 'Site', summary: 'Check in with the Hub now', access: 'admin', body: loose, v1: hub.heartbeatNow }); -v1Route({ method: 'post', path: '/hub/update-request', tag: 'Site', summary: 'Ask for the update to be installed', access: 'admin', body: loose, v1: hub.requestUpdate }); -v1Route({ method: 'post', path: '/hub/update-request/cancel', tag: 'Site', summary: 'Withdraw the update request', access: 'admin', body: loose, v1: hub.cancelUpdateRequest }); -v1Route({ method: 'post', path: '/hub/update-snooze', tag: 'Site', summary: 'Remind me about the update later', access: 'admin', body: loose, v1: hub.snoozeUpdate }); +v1Route({ method: 'get', path: '/hub/status', tag: 'Site', summary: 'The connection to the provider\'s Hub', access: 'admin', documented: { response: hubStatus }, v1: hub.getStatus }); +v1Route({ method: 'post', path: '/hub/connect', tag: 'Site', summary: 'Connect to the Hub', access: 'admin', body: loose, documented: { body: D.obj({ licenceKey: D.str }), response: hubStatus }, v1: hub.connect }); +v1Route({ method: 'post', path: '/hub/heartbeat', tag: 'Site', summary: 'Check in with the Hub now', access: 'admin', body: loose, documented: { response: hubStatus }, v1: hub.heartbeatNow }); +v1Route({ method: 'post', path: '/hub/update-request', tag: 'Site', summary: 'Ask for the update to be installed', access: 'admin', body: loose, documented: { response: hubStatus }, v1: hub.requestUpdate }); +v1Route({ method: 'post', path: '/hub/update-request/cancel', tag: 'Site', summary: 'Withdraw the update request', access: 'admin', body: loose, documented: { response: hubStatus }, v1: hub.cancelUpdateRequest }); +v1Route({ method: 'post', path: '/hub/update-snooze', tag: 'Site', summary: 'Remind me about the update later', access: 'admin', body: loose, documented: { body: D.obj({ snooze: D.optBool.describe('false: stop putting it off') }), response: hubStatus }, v1: hub.snoozeUpdate }); v1Route({ method: 'get', path: '/hub/notices', tag: 'Site', summary: 'Notices from the provider', - access: 'supervisor', campusScope: 'campusIndependent (notices from the provider are for the whole site)', middleware: [campusIndependent('notices from the provider are for the whole site')], v1: hub.getNotices, + access: 'supervisor', campusScope: 'campusIndependent (notices from the provider are for the whole site)', middleware: [campusIndependent('notices from the provider are for the whole site')], documented: { response: z.array(D.obj({ id: D.str, level: D.str.describe('info, warning, critical'), title: D.str, message: D.str, startsAt: D.optDate, endsAt: D.optDate, updatedAt: D.optDate })) }, v1: hub.getNotices, }); // ─── Outbound webhooks ─────────────────────────────────────────────────────── -v1Route({ method: 'get', path: '/outbound-webhooks', tag: 'Webhooks', summary: 'Webhooks the site sends', access: 'admin', v1: hooks.list }); -v1Route({ method: 'post', path: '/outbound-webhooks', tag: 'Webhooks', summary: 'Add a webhook', description: 'Answers its signing secret once.', access: 'admin', status: 201, body: loose, v1: hooks.create }); -v1Route({ method: 'post', path: '/outbound-webhook-deliveries/:id/resend', tag: 'Webhooks', summary: 'Send a delivery again', access: 'admin', params: idParams, body: loose, v1: hooks.resend }); -v1Route({ method: 'patch', path: '/outbound-webhooks/:id', tag: 'Webhooks', summary: 'Change a webhook', access: 'admin', params: idParams, body: loose, v1: hooks.update }); -v1Route({ method: 'delete', path: '/outbound-webhooks/:id', tag: 'Webhooks', summary: 'Remove a webhook', access: 'admin', params: idParams, v1: hooks.remove }); -v1Route({ method: 'post', path: '/outbound-webhooks/:id/rotate-secret', tag: 'Webhooks', summary: 'Give a webhook a new signing secret', access: 'admin', params: idParams, body: loose, v1: hooks.rotateSecret }); -v1Route({ method: 'post', path: '/outbound-webhooks/:id/test', tag: 'Webhooks', summary: 'Send a test delivery', access: 'admin', params: idParams, body: loose, v1: hooks.test }); -v1Route({ method: 'get', path: '/outbound-webhooks/:id/deliveries', tag: 'Webhooks', summary: 'A webhook\'s recent deliveries', access: 'admin', params: idParams, query: filters('page', 'limit'), v1: hooks.deliveries }); +v1Route({ method: 'get', path: '/outbound-webhooks', tag: 'Webhooks', summary: 'Webhooks the site sends', access: 'admin', documented: { response: D.obj({ eventTypes: z.array(D.anyObj).describe('Every event type, with an example body'), keepDays: D.num.describe('How long deliveries are kept'), endpoints: z.array(webhook.extend({ lastWeek: z.record(z.string(), z.number()).describe('Status → deliveries in the last 7 days') })) }) }, v1: hooks.list }); +v1Route({ method: 'post', path: '/outbound-webhooks', tag: 'Webhooks', summary: 'Add a webhook', description: 'Answers its signing secret once.', access: 'admin', status: 201, body: loose, documented: { body: D.obj({ name: D.str, url: D.str.describe('https:// address'), events: z.array(D.str) }), response: webhook.extend({ secret: D.str.describe('For checking signatures — shown only now') }) }, v1: hooks.create }); +v1Route({ method: 'post', path: '/outbound-webhook-deliveries/:id/resend', tag: 'Webhooks', summary: 'Send a delivery again', access: 'admin', params: idParams, body: loose, documented: { response: delivered }, v1: hooks.resend }); +v1Route({ method: 'patch', path: '/outbound-webhooks/:id', tag: 'Webhooks', summary: 'Change a webhook', access: 'admin', params: idParams, body: loose, documented: { body: D.obj({ name: D.optStr, url: D.optStr, events: z.array(D.str).optional(), isActive: D.optBool }), response: webhook }, v1: hooks.update }); +v1Route({ method: 'delete', path: '/outbound-webhooks/:id', tag: 'Webhooks', summary: 'Remove a webhook', access: 'admin', params: idParams, documented: { response: D.ok }, v1: hooks.remove }); +v1Route({ method: 'post', path: '/outbound-webhooks/:id/rotate-secret', tag: 'Webhooks', summary: 'Give a webhook a new signing secret', access: 'admin', params: idParams, body: loose, documented: { response: D.obj({ secret: D.str.describe('Shown only now; the old one stops working') }) }, v1: hooks.rotateSecret }); +v1Route({ method: 'post', path: '/outbound-webhooks/:id/test', tag: 'Webhooks', summary: 'Send a test delivery', access: 'admin', params: idParams, body: loose, documented: { response: delivered }, v1: hooks.test }); +v1Route({ method: 'get', path: '/outbound-webhooks/:id/deliveries', tag: 'Webhooks', summary: 'A webhook\'s recent deliveries', access: 'admin', params: idParams, query: filters('page', 'limit', 'status', 'before'), documented: { response: z.array(D.obj({ id: D.str, eventId: D.str, type: D.str.describe('The event type'), payload: z.unknown(), status: D.str.describe('pending, sending, retrying, succeeded, failed'), attempts: D.num, nextAttemptAt: D.optDate, lastStatusCode: D.optNum, lastError: D.optStr, createdAt: D.date, deliveredAt: D.optDate })) }, v1: hooks.deliveries }); // ─── Backups ───────────────────────────────────────────────────────────────── -v1Route({ method: 'get', path: '/backups', tag: 'Admin', summary: 'Database backups', access: 'admin', v1: backups.getBackups }); -v1Route({ method: 'post', path: '/backups/run', tag: 'Admin', summary: 'Back up the database now', access: 'admin', body: loose, v1: backups.triggerBackup }); +v1Route({ method: 'get', path: '/backups', tag: 'Admin', summary: 'Database backups', access: 'admin', documented: { response: z.array(D.obj({ filename: D.str, size: D.num.describe('Bytes'), createdAt: D.date })) }, v1: backups.getBackups }); +v1Route({ method: 'post', path: '/backups/run', tag: 'Admin', summary: 'Back up the database now', access: 'admin', body: loose, documented: { response: D.anyObj.describe('The backup made') }, v1: backups.triggerBackup }); v1Route({ method: 'get', path: '/backups/:filename/download', tag: 'Admin', summary: 'Download a backup', access: 'admin', params: z.object({ filename: z.string().min(1).max(200) }), file: { contentType: 'application/octet-stream' }, v1: backups.downloadBackup }); // ─── Yoco and PayFast settings (admins; their incoming webhooks are separate) ─ const yoco = require('../../controllers/yocoController'); const payfast = require('../../controllers/payfastController'); -v1Route({ method: 'get', path: '/payments/yoco/config', tag: 'Payments', summary: 'Yoco settings', description: 'Keys are masked.', access: 'admin', v1: yoco.getConfig }); -v1Route({ method: 'put', path: '/payments/yoco/config', tag: 'Payments', summary: 'Change Yoco settings', access: 'admin', body: loose, v1: yoco.updateConfig }); -v1Route({ method: 'get', path: '/payments/yoco/webhooks', tag: 'Payments', summary: 'Webhooks registered with Yoco', access: 'admin', v1: yoco.getWebhooks }); -v1Route({ method: 'post', path: '/payments/yoco/webhooks', tag: 'Payments', summary: 'Register a webhook with Yoco', access: 'admin', body: loose, v1: yoco.createWebhook }); -v1Route({ method: 'delete', path: '/payments/yoco/webhooks/:id', tag: 'Payments', summary: 'Remove a webhook from Yoco', access: 'admin', params: z.object({ id: z.string().min(1).max(200) }), v1: yoco.removeWebhook }); -v1Route({ method: 'get', path: '/payments/payfast/config', tag: 'Payments', summary: 'PayFast settings', description: 'The passphrase is masked.', access: 'admin', v1: payfast.getConfig }); -v1Route({ method: 'put', path: '/payments/payfast/config', tag: 'Payments', summary: 'Change PayFast settings', access: 'admin', body: loose, v1: payfast.updateConfig }); -v1Route({ method: 'post', path: '/payments/payfast/test', tag: 'Payments', summary: 'Check the PayFast details work', access: 'admin', body: loose, v1: payfast.testConnection }); +v1Route({ method: 'get', path: '/payments/yoco/config', tag: 'Payments', summary: 'Yoco settings', description: 'Keys are masked.', access: 'admin', documented: { response: D.obj({ secretKeyMasked: D.str, secretKeySource: D.optStr.describe('settings or env'), mode: D.optStr.describe('test or live'), webhookSecretMasked: D.str, webhookSecretSource: D.optStr, webhookId: D.str, webhookUrl: D.str, configured: D.bool }) }, v1: yoco.getConfig }); +v1Route({ method: 'put', path: '/payments/yoco/config', tag: 'Payments', summary: 'Change Yoco settings', access: 'admin', body: loose, documented: { body: D.obj({ secretKey: D.optStr.describe('sk_test_… or sk_live_…'), webhookSecret: D.optStr.describe('whsec_…') }), response: D.message }, v1: yoco.updateConfig }); +v1Route({ method: 'get', path: '/payments/yoco/webhooks', tag: 'Payments', summary: 'Webhooks registered with Yoco', access: 'admin', documented: { response: D.obj({ webhooks: z.array(D.obj({ id: D.str, name: D.optStr, url: D.str, mode: D.optStr, isActive: D.bool, pointsHere: D.bool })), defaultUrl: D.str }) }, v1: yoco.getWebhooks }); +v1Route({ method: 'post', path: '/payments/yoco/webhooks', tag: 'Payments', summary: 'Register a webhook with Yoco', access: 'admin', body: loose, documented: { body: D.obj({ name: D.optStr, url: D.optStr.describe('Default: this site\'s webhook address') }), response: D.obj({ message: D.str, webhook: D.obj({ id: D.str, name: D.optStr, url: D.str, mode: D.optStr }), webhookSecretMasked: D.str }) }, v1: yoco.createWebhook }); +v1Route({ method: 'delete', path: '/payments/yoco/webhooks/:id', tag: 'Payments', summary: 'Remove a webhook from Yoco', access: 'admin', params: z.object({ id: z.string().min(1).max(200) }), documented: { response: D.obj({ message: D.str, clearedSecret: D.bool }) }, v1: yoco.removeWebhook }); +v1Route({ method: 'get', path: '/payments/payfast/config', tag: 'Payments', summary: 'PayFast settings', description: 'The passphrase is masked.', access: 'admin', documented: { response: D.obj({ merchantId: D.str, merchantKey: D.str, passphraseMasked: D.str, hasPassphrase: D.bool, mode: z.enum(['sandbox', 'live']), notifyUrl: D.str, notifyUrlProblem: D.optStr.describe('Why PayFast couldn\'t reach it'), configured: D.bool }) }, v1: payfast.getConfig }); +v1Route({ method: 'put', path: '/payments/payfast/config', tag: 'Payments', summary: 'Change PayFast settings', access: 'admin', body: loose, documented: { body: D.obj({ merchantId: D.optStr, merchantKey: D.optStr, passphrase: D.optStr.describe('At most 32 characters'), mode: z.enum(['sandbox', 'live']).optional() }), response: D.message }, v1: payfast.updateConfig }); +v1Route({ method: 'post', path: '/payments/payfast/test', tag: 'Payments', summary: 'Check the PayFast details work', access: 'admin', body: loose, documented: { response: D.message }, v1: payfast.testConnection }); diff --git a/apps/events/backend/src/v2/resources/attendance.ts b/apps/events/backend/src/v2/resources/attendance.ts index c1fbdf0..7415c71 100644 --- a/apps/events/backend/src/v2/resources/attendance.ts +++ b/apps/events/backend/src/v2/resources/attendance.ts @@ -7,6 +7,7 @@ import { z } from 'zod'; import { id, idParams } from '../schemas'; import { v1Route } from '../viaV1'; +import * as D from '../docs'; /* eslint-disable @typescript-eslint/no-explicit-any -- v1 handlers and middleware are JavaScript */ const cs = require('../../utils/campusScope') as { @@ -25,114 +26,148 @@ const asEvent = (ctx: any) => ({ params: { ...ctx.req.params, eventId: ctx.param const loose = z.looseObject({}); const tokenParams = z.object({ token: z.string().min(1).max(200) }); const SCOPE_LIST = 'scopeList (the handler filters by listWhere)'; + +// ─── Documented shapes (docs.ts) ───────────────────────────────────────────── + +const usage = D.obj({ id: D.str.optional(), scannedAt: D.date, quantityRedeemed: D.num, sessionId: D.optStr, manual: D.optBool.describe('Ticked present by hand') }); +const ticketFull = D.ticket.extend({ + usages: z.array(usage).optional().describe('Check-ins'), + event: D.event.partial().nullish(), + user: D.userSummary.nullish().describe('The payer'), + attendee: D.obj({ name: D.str }).nullish(), + registrationOption: D.obj({ eventOption: D.eventOption.partial().nullish(), variant: D.obj({ name: D.str }).nullish(), registration: D.registration.partial().nullish() }).nullish(), +}); +const sent = D.obj({ message: D.str, ticketIds: D.ids.optional().describe('The tickets sent') }); +const lockView = D.obj({ + id: D.str, eventId: D.str, sectionId: D.optStr, sectionName: D.optStr, deviceId: D.str, deviceName: D.optStr, + user: D.userRef.nullish().describe('Who holds it'), lockedAt: D.date, snapshotAt: D.optDate, lastSyncAt: D.optDate, releasedAt: D.optDate, +}); +const transferInput = D.obj({ + name: D.str.describe('Who it goes to'), email: D.optStr, phone: D.optStr.describe('Email or phone needed'), + dateOfBirth: D.optDate.describe('Youth events'), gender: D.optStr, parentName: D.optStr, parentEmail: D.optStr, parentPhone: D.optStr, +}); +const certificate = D.obj({ id: D.str, code: D.str.describe('For checking it at /verify'), name: D.str, issuedAt: D.date, sessionsAttended: D.optNum, totalSessions: D.optNum, event: D.eventRef.partial().nullish() }); +const registerRow = D.obj({ + ticketId: D.str, bookedSessions: D.ids.nullable().describe('Picked/ticked sessions (null: all)'), sessionTickets: z.record(z.string(), z.string()).nullable(), + name: D.str, bookedBy: D.str, email: D.str, phone: D.str, option: D.str, variant: D.optStr, quantity: D.num, + checkIns: z.record(z.string(), z.number()).describe('Session id (or `event`) → people checked in'), + attended: D.num, total: D.num, completed: D.bool.describe('Meets the certificate rule'), certificate: D.anyObj.nullish(), +}); +const groupInput = D.obj({ + name: D.optStr, capacity: D.numeric.nullish(), gender: z.enum(['male', 'female', 'mixed']).nullish(), leaderUserId: D.optStr.describe('A staff member'), + minAge: D.numeric.nullish(), maxAge: D.numeric.nullish(), ratio: D.numeric.nullish().describe('Children per leader'), +}); +const group = D.obj({ id: D.str, setId: D.str, name: D.str, capacity: D.optNum, gender: D.optStr, leaderUserId: D.optStr, minAge: D.optNum, maxAge: D.optNum, ratio: D.optNum, order: D.num }); +const allocationSet = D.obj({ id: D.str, eventId: D.str, name: D.str, showOnTicket: D.bool, order: D.num }); +const member = D.obj({ attendeeId: D.str.optional(), name: D.str, gender: D.optStr, dateOfBirth: D.optDate, groupId: D.optStr }); const ticketOwner = cs.scopeEvent({ resolve: 'ticket', ownerOk: true }); const qrScope = cs.scopeEvent({ resolve: 'ticketQr', from: (req: any) => req.params.qrCode, nameCampus: true }); // ─── Tickets ───────────────────────────────────────────────────────────────── -v1Route({ method: 'get', path: '/me/tickets', tag: 'Tickets', summary: 'My tickets', description: 'Including ones transferred to me.', access: 'user', v1: t.getUserTickets }); +v1Route({ method: 'get', path: '/me/tickets', tag: 'Tickets', summary: 'My tickets', description: 'Including ones transferred to me.', access: 'user', documented: { response: z.array(ticketFull) }, v1: t.getUserTickets }); v1Route({ method: 'post', path: '/me/tickets/email', tag: 'Tickets', summary: 'Send me my tickets', description: 'For a registration (`registrationId`) or chosen tickets (`ticketIds`), by email and/or WhatsApp (`channel`).', - access: 'user', body: z.looseObject({ registrationId: id.optional(), ticketIds: z.array(id).max(500).optional(), channel: z.string().max(20).optional() }), v1: t.emailTickets, + access: 'user', body: z.looseObject({ registrationId: id.optional(), ticketIds: z.array(id).max(500).optional(), channel: z.string().max(20).optional() }), documented: { response: sent }, v1: t.emailTickets, }); v1Route({ - method: 'get', path: '/tickets/scans/recent', tag: 'Tickets', summary: 'Recent scans', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventId', 'limit'), v1: t.getRecentScans, + method: 'get', path: '/tickets/scans/recent', tag: 'Tickets', summary: 'Recent scans', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventId', 'limit'), documented: { response: z.array(D.obj({ id: D.str, scannedAt: D.date, quantityRedeemed: D.num, scannedBy: D.userRef.nullish(), ticket: D.obj({ id: D.str, event: D.obj({ title: D.str }), registrationOption: D.anyObj.nullish() }) })) }, v1: t.getRecentScans, }); v1Route({ - method: 'get', path: '/tickets/scans/stats', tag: 'Tickets', summary: 'Scan counts', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventId'), v1: t.getScanStats, + method: 'get', path: '/tickets/scans/stats', tag: 'Tickets', summary: 'Scan counts', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventId'), documented: { response: D.obj({ totalToday: D.num, myToday: D.num, lastHour: D.num, byStaff: z.array(D.obj({ scannedById: D.str, name: D.str, count: D.num })) }) }, v1: t.getScanStats, }); v1Route({ method: 'post', path: '/tickets/send', tag: 'Tickets', summary: 'Send tickets to someone', description: 'Staff: a registration\'s tickets (or chosen ones) to an email address or phone number.', - access: 'staff', campusScope: 'scopeBody(registrationId, ticketIds)', middleware: [cs.scopeBody([['registrationId', 'registration'], ['ticketIds', 'ticket']])], body: loose, v1: t.sendTicketsTo, + access: 'staff', campusScope: 'scopeBody(registrationId, ticketIds)', middleware: [cs.scopeBody([['registrationId', 'registration'], ['ticketIds', 'ticket']])], body: loose, documented: { body: D.obj({ registrationId: D.optStr, ticketIds: D.ids.optional().describe('Or registrationId'), channel: D.channel, overrideEmail: D.optStr.describe('Send here instead'), overridePhone: D.optStr }), response: sent }, v1: t.sendTicketsTo, }); v1Route({ method: 'post', path: '/tickets/generate', tag: 'Tickets', summary: 'Issue a registration\'s tickets', - access: 'supervisor', campusScope: 'scopeBody(registrationId)', middleware: [cs.scopeBody([['registrationId', 'registration']])], body: z.looseObject({ registrationId: id }), v1: t.generateTickets, + access: 'supervisor', campusScope: 'scopeBody(registrationId)', middleware: [cs.scopeBody([['registrationId', 'registration']])], body: z.looseObject({ registrationId: id }), documented: { response: D.obj({ message: D.str, tickets: z.array(ticketFull) }) }, v1: t.generateTickets, }); v1Route({ - method: 'post', path: '/tickets/email-sent', tag: 'Tickets', summary: 'Mark tickets as emailed', access: 'admin', body: loose, v1: t.markTicketsAsEmailSent, + method: 'post', path: '/tickets/email-sent', tag: 'Tickets', summary: 'Mark tickets as emailed', access: 'admin', body: loose, documented: { body: D.obj({ ticketIds: D.ids }), response: D.message }, v1: t.markTicketsAsEmailSent, }); v1Route({ - method: 'get', path: '/tickets', tag: 'Tickets', summary: 'Every ticket', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventId', 'page', 'limit'), v1: t.getTickets, + method: 'get', path: '/tickets', tag: 'Tickets', summary: 'Every ticket', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventId', 'page', 'limit'), documented: { response: D.v1Page(ticketFull) }, v1: t.getTickets, }); v1Route({ method: 'get', path: '/tickets/qr/:qrCode', tag: 'Tickets', summary: 'The ticket for a QR code', description: 'Without checking it in (that\'s POST /checkin/{qrCode}).', - access: 'staff', campusScope: 'scopeEvent(ticketQr)', middleware: [qrScope], params: z.object({ qrCode: z.string().min(1).max(200) }), v1: t.getTicketByQrCode, + access: 'staff', campusScope: 'scopeEvent(ticketQr)', middleware: [qrScope], params: z.object({ qrCode: z.string().min(1).max(200) }), documented: { response: ticketFull }, v1: t.getTicketByQrCode, }); v1Route({ method: 'get', path: '/events/:id/tickets', tag: 'Tickets', summary: 'An event\'s tickets', - access: 'staff', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, v1: t.getTicketsByEvent, + access: 'staff', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, documented: { response: z.array(ticketFull) }, v1: t.getTicketsByEvent, }); v1Route({ method: 'get', path: '/ticket-transfers/:token', tag: 'Tickets', summary: 'A ticket someone is giving you', - description: 'What the transfer link shows (the token is the credential).', access: 'public', params: tokenParams, v1: t.getTransferOffer, + description: 'What the transfer link shows (the token is the credential).', access: 'public', params: tokenParams, documented: { response: D.obj({ status: D.str.describe('pending, accepted, declined, cancelled, expired'), toName: D.str, expiresAt: D.date, fromName: D.str, event: D.event.partial(), option: D.str }) }, v1: t.getTransferOffer, }); -v1Route({ method: 'post', path: '/ticket-transfers/:token/accept', tag: 'Tickets', summary: 'Accept a ticket', access: 'public', params: tokenParams, body: loose, v1: t.acceptTransferOffer }); -v1Route({ method: 'post', path: '/ticket-transfers/:token/decline', tag: 'Tickets', summary: 'Decline a ticket', access: 'public', params: tokenParams, body: loose, v1: t.declineTransferOffer }); +v1Route({ method: 'post', path: '/ticket-transfers/:token/accept', tag: 'Tickets', summary: 'Accept a ticket', access: 'public', params: tokenParams, body: loose, documented: { response: D.obj({ message: D.str, ticketId: D.str }) }, v1: t.acceptTransferOffer }); +v1Route({ method: 'post', path: '/ticket-transfers/:token/decline', tag: 'Tickets', summary: 'Decline a ticket', access: 'public', params: tokenParams, body: loose, documented: { response: D.message }, v1: t.declineTransferOffer }); v1Route({ - method: 'get', path: '/tickets/:id', tag: 'Tickets', summary: 'One ticket', access: 'user', campusScope: 'scopeEvent(ticket, owner-ok)', middleware: [ticketOwner], params: idParams, v1: t.getTicketById, + method: 'get', path: '/tickets/:id', tag: 'Tickets', summary: 'One ticket', access: 'user', campusScope: 'scopeEvent(ticket, owner-ok)', middleware: [ticketOwner], params: idParams, documented: { response: ticketFull }, v1: t.getTicketById, }); v1Route({ method: 'post', path: '/tickets/:id/transfer', tag: 'Tickets', summary: 'Give a ticket to someone', description: 'Sends them a link to accept it; the ticket is theirs once they do.', - access: 'user', campusScope: 'scopeEvent(ticket, owner-ok)', middleware: [ticketOwner], params: idParams, body: loose, v1: t.transferTicketHandler, + access: 'user', campusScope: 'scopeEvent(ticket, owner-ok)', middleware: [ticketOwner], params: idParams, body: loose, documented: { body: transferInput, response: D.obj({ message: D.str, requestId: D.str, expiresAt: D.date }) }, v1: t.transferTicketHandler, }); v1Route({ - method: 'delete', path: '/tickets/:id/transfer', tag: 'Tickets', summary: 'Cancel a ticket transfer', access: 'user', campusScope: 'scopeEvent(ticket, owner-ok)', middleware: [ticketOwner], params: idParams, v1: t.cancelTransferHandler, + method: 'delete', path: '/tickets/:id/transfer', tag: 'Tickets', summary: 'Cancel a ticket transfer', access: 'user', campusScope: 'scopeEvent(ticket, owner-ok)', middleware: [ticketOwner], params: idParams, documented: { response: D.message }, v1: t.cancelTransferHandler, }); v1Route({ - method: 'get', path: '/tickets/:id/transfers', tag: 'Tickets', summary: 'A ticket\'s transfers', access: 'user', campusScope: 'scopeEvent(ticket, owner-ok)', middleware: [ticketOwner], params: idParams, v1: t.getTicketTransfers, + method: 'get', path: '/tickets/:id/transfers', tag: 'Tickets', summary: 'A ticket\'s transfers', access: 'user', campusScope: 'scopeEvent(ticket, owner-ok)', middleware: [ticketOwner], params: idParams, documented: { response: z.array(D.obj({ id: D.str, ticketId: D.str, fromUserId: D.optStr, toUserId: D.optStr, createdAt: D.date })) }, v1: t.getTicketTransfers, }); // ─── Scan locks (offline scanning) ─────────────────────────────────────────── v1Route({ method: 'get', path: '/scan-locks', tag: 'Check-in', summary: 'Devices scanning offline for an event', - access: 'staff', campusScope: 'scopeEvent(query.eventId)', middleware: [cs.scopeEvent({ from: (req: any) => req.query.eventId })], query: z.looseObject({ eventId: id }), v1: locks.listLocks, + access: 'staff', campusScope: 'scopeEvent(query.eventId)', middleware: [cs.scopeEvent({ from: (req: any) => req.query.eventId })], query: z.looseObject({ eventId: id }), documented: { response: z.array(lockView) }, v1: locks.listLocks, }); v1Route({ method: 'post', path: '/scan-locks', tag: 'Check-in', summary: 'Take tickets offline on this device', description: 'Locks the chosen tickets to this device until it syncs or releases them.', - access: 'staff', campusScope: 'scopeEvent(body.eventId)', middleware: [cs.scopeEvent({ from: (req: any) => req.body?.eventId })], status: 201, body: z.looseObject({ eventId: id }), v1: locks.createLock, + access: 'staff', campusScope: 'scopeEvent(body.eventId)', middleware: [cs.scopeEvent({ from: (req: any) => req.body?.eventId })], status: 201, body: z.looseObject({ eventId: id }), documented: { body: D.obj({ eventId: D.str, sectionId: D.optStr.describe('Just this section (default: the whole event)'), deviceId: D.str, deviceName: D.optStr }), response: lockView }, v1: locks.createLock, }); v1Route({ method: 'get', path: '/scan-locks/reports', tag: 'Check-in', summary: 'Offline sync reports to review', - access: 'supervisor', campusScope: 'scopeEvent(query.eventId)', middleware: [cs.scopeEvent({ from: (req: any) => req.query.eventId })], query: z.looseObject({ eventId: id, unreviewed: z.string().max(10).optional() }), v1: locks.listReports, + access: 'supervisor', campusScope: 'scopeEvent(query.eventId)', middleware: [cs.scopeEvent({ from: (req: any) => req.query.eventId })], query: z.looseObject({ eventId: id, unreviewed: z.string().max(10).optional() }), documented: { response: z.array(D.obj({ id: D.str, accepted: D.optNum, duplicates: D.optNum, conflicts: z.unknown().optional(), reviewedAt: D.optDate, createdAt: D.date, scanLock: lockView })) }, v1: locks.listReports, }); v1Route({ method: 'post', path: '/scan-locks/reports/:id/review', tag: 'Check-in', summary: 'Mark a sync report reviewed', - access: 'supervisor', campusScope: 'scopeEvent(syncReport)', middleware: [cs.scopeEvent({ resolve: 'syncReport' })], params: idParams, body: loose, v1: locks.reviewReport, + access: 'supervisor', campusScope: 'scopeEvent(syncReport)', middleware: [cs.scopeEvent({ resolve: 'syncReport' })], params: idParams, body: loose, documented: { response: D.obj({ id: D.str, reviewedAt: D.date, reviewedById: D.str }) }, v1: locks.reviewReport, }); v1Route({ method: 'get', path: '/scan-locks/:id/snapshot', tag: 'Check-in', summary: 'The tickets a device took offline', - access: 'staff', campusScope: 'scopeEvent(scanLock)', middleware: [cs.scopeEvent({ resolve: 'scanLock' })], params: idParams, query: filters('deviceId'), v1: locks.getSnapshot, + access: 'staff', campusScope: 'scopeEvent(scanLock)', middleware: [cs.scopeEvent({ resolve: 'scanLock' })], params: idParams, query: filters('deviceId'), documented: { response: D.obj({ lock: lockView, snapshotAt: D.date, session: D.obj({ id: D.str, label: D.str }).nullable(), noSessionToday: D.bool, tickets: z.array(D.obj({ id: D.str, qrCode: D.str, holder: D.str, bookedBy: D.str, option: D.str, variant: D.optStr, quantity: D.num, remaining: D.num, consentStatus: D.str })) }) }, v1: locks.getSnapshot, }); v1Route({ method: 'post', path: '/scan-locks/:id/sync', tag: 'Check-in', summary: 'Upload scans made offline', - access: 'staff', campusScope: 'scopeEvent(scanLock)', middleware: [cs.scopeEvent({ resolve: 'scanLock' })], params: idParams, body: loose, v1: locks.syncLock, + access: 'staff', campusScope: 'scopeEvent(scanLock)', middleware: [cs.scopeEvent({ resolve: 'scanLock' })], params: idParams, body: loose, documented: { body: D.obj({ deviceId: D.str, scans: z.array(D.obj({ clientScanId: D.str.describe('The device\'s id for the scan (repeats are ignored)'), qrCode: D.str, qty: D.numeric.optional(), scannedAt: D.optDate, sessionId: D.optStr })).max(2000) }), response: D.obj({ accepted: D.num, duplicates: D.num, conflicts: z.array(D.anyObj).describe('Scans that clashed with online check-ins'), reportId: D.str, released: D.bool }) }, v1: locks.syncLock, }); v1Route({ method: 'post', path: '/scan-locks/:id/force-release', tag: 'Check-in', summary: 'Release a lost device\'s tickets', - access: 'supervisor', campusScope: 'scopeEvent(scanLock)', middleware: [cs.scopeEvent({ resolve: 'scanLock' })], params: idParams, body: loose, v1: locks.forceRelease, + access: 'supervisor', campusScope: 'scopeEvent(scanLock)', middleware: [cs.scopeEvent({ resolve: 'scanLock' })], params: idParams, body: loose, documented: { response: D.message }, v1: locks.forceRelease, }); v1Route({ method: 'delete', path: '/scan-locks/:id', tag: 'Check-in', summary: 'Release tickets back online', - access: 'staff', campusScope: 'scopeEvent(scanLock)', middleware: [cs.scopeEvent({ resolve: 'scanLock' })], params: idParams, body: z.looseObject({ deviceId: z.string().max(200).optional() }), v1: locks.releaseLock, + access: 'staff', campusScope: 'scopeEvent(scanLock)', middleware: [cs.scopeEvent({ resolve: 'scanLock' })], params: idParams, body: z.looseObject({ deviceId: z.string().max(200).optional() }), documented: { response: D.message }, v1: locks.releaseLock, }); // ─── Attendance and certificates ───────────────────────────────────────────── v1Route({ method: 'get', path: '/certificates/verify/:code', tag: 'Attendance', summary: 'Check a certificate is genuine', - access: 'public', params: z.object({ code: z.string().min(1).max(100) }), v1: att.verifyCertificate, + access: 'public', params: z.object({ code: z.string().min(1).max(100) }), documented: { response: D.obj({ valid: D.bool, revoked: D.optBool, name: D.optStr, event: D.optStr, completedOn: D.optDate, issuedAt: D.optDate }) }, v1: att.verifyCertificate, }); -v1Route({ method: 'get', path: '/me/certificates', tag: 'Me', summary: 'My certificates', access: 'user', v1: att.myCertificates }); +v1Route({ method: 'get', path: '/me/certificates', tag: 'Me', summary: 'My certificates', access: 'user', documented: { response: z.array(certificate) }, v1: att.myCertificates }); v1Route({ method: 'post', path: '/certificates/preview', tag: 'Attendance', summary: 'Preview a certificate template', - access: 'supervisor', campusScope: 'campusIndependent (previews a template from the request body)', middleware: [cs.campusIndependent('previews a certificate template from the request body')], body: loose, file: { contentType: 'application/pdf' }, v1: att.previewCertificate, + access: 'supervisor', campusScope: 'campusIndependent (previews a template from the request body)', middleware: [cs.campusIndependent('previews a certificate template from the request body')], body: loose, file: { contentType: 'application/pdf' }, documented: { body: D.obj({ title: D.optStr.describe('Event title to show'), config: D.obj({ template: D.optStr.describe('classic, modern, elegant, simple'), title: D.optStr, body: D.optStr.describe('{name} and {event} are filled in') }).optional() }) }, v1: att.previewCertificate, }); v1Route({ method: 'get', path: '/certificates/:id/pdf', tag: 'Attendance', summary: 'Download a certificate', @@ -140,11 +175,11 @@ v1Route({ }); v1Route({ method: 'post', path: '/certificates/:id/revoke', tag: 'Attendance', summary: 'Withdraw a certificate', - access: 'supervisor', campusScope: 'scopeEvent(certificate)', middleware: [cs.scopeEvent({ resolve: 'certificate' })], params: idParams, body: loose, v1: att.revokeCertificate, + access: 'supervisor', campusScope: 'scopeEvent(certificate)', middleware: [cs.scopeEvent({ resolve: 'certificate' })], params: idParams, body: loose, documented: { response: D.ok }, v1: att.revokeCertificate, }); v1Route({ method: 'get', path: '/events/:id/attendance', tag: 'Attendance', summary: 'An event\'s attendance register', - access: 'staff', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, v1: att.getRegister, + access: 'staff', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, documented: { response: D.obj({ event: D.event.partial().extend({ certificatesEnabled: D.optBool, certificateConfig: D.anyObj.nullish() }), columns: z.array(D.obj({ id: D.str.describe('Session id, or `event`'), label: D.str })), rows: z.array(registerRow), totals: z.record(z.string(), z.number()) }) }, v1: att.getRegister, }); v1Route({ method: 'get', path: '/events/:id/attendance/export', tag: 'Attendance', summary: 'The register as a file', @@ -153,15 +188,15 @@ v1Route({ }); v1Route({ method: 'post', path: '/events/:id/attendance', tag: 'Attendance', summary: 'Mark attendance', - access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, body: loose, map: asEvent, v1: att.markAttendance, + access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, body: loose, map: asEvent, documented: { body: D.obj({ ticketId: D.str, sessionId: D.str.describe('A session id, or `event` on a single-date event'), present: D.bool }), response: D.ok }, v1: att.markAttendance, }); v1Route({ method: 'post', path: '/events/:id/certificates', tag: 'Attendance', summary: 'Issue certificates', - access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, body: loose, map: asEvent, v1: att.issueCertificates, + access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, body: loose, map: asEvent, documented: { body: D.obj({ ticketId: D.optStr.describe('Just this person (default: everyone who qualifies)') }), response: D.obj({ issued: D.num }) }, v1: att.issueCertificates, }); v1Route({ method: 'post', path: '/events/:id/certificates/send', tag: 'Attendance', summary: 'Send certificates', - access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, body: loose, map: asEvent, v1: att.sendCertificatesHandler, + access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, body: loose, map: asEvent, documented: { body: D.obj({ certificateId: D.optStr.describe('Just this one (default: every one not sent yet)') }), response: D.obj({ sent: D.num, skipped: D.num }) }, v1: att.sendCertificatesHandler, }); v1Route({ method: 'get', path: '/events/:id/certificates.pdf', tag: 'Attendance', summary: 'Every certificate for an event, as one PDF', @@ -172,24 +207,24 @@ v1Route({ v1Route({ method: 'get', path: '/me/allocation-groups', tag: 'Allocations', summary: 'Groups I lead', - access: 'staff', campusScope: 'campusIndependent (only the groups the signed-in person leads)', middleware: [cs.campusIndependent('only the groups the signed-in person leads')], v1: alloc.getMyGroups, + access: 'staff', campusScope: 'campusIndependent (only the groups the signed-in person leads)', middleware: [cs.campusIndependent('only the groups the signed-in person leads')], documented: { response: D.obj({ medicalShown: D.bool, groups: z.array(D.obj({ id: D.str, name: D.str, capacity: D.optNum, gender: D.optStr, setName: D.str, event: D.eventRef.partial(), members: z.array(member) })) }) }, v1: alloc.getMyGroups, }); v1Route({ method: 'get', path: '/events/:id/allocations', tag: 'Allocations', summary: 'An event\'s allocation board', - access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, v1: alloc.getBoard, + access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, documented: { response: D.obj({ event: D.anyObj, sets: z.array(allocationSet.extend({ groups: z.array(group), assignments: z.array(D.obj({ attendeeId: D.str, groupId: D.str })) })), attendees: z.array(D.obj({ id: D.str, name: D.str, gender: D.optStr, dateOfBirth: D.optDate, registrationId: D.str, bookedBy: D.str })), leaders: z.array(D.userRef), unnamedPlaces: D.num.describe('Places with no name yet') }) }, v1: alloc.getBoard, }); v1Route({ method: 'post', path: '/allocation-sets', tag: 'Allocations', summary: 'Start a set of groups', - access: 'supervisor', campusScope: 'scopeEvent(body.eventId)', middleware: [cs.scopeEvent({ from: (req: any) => req.body?.eventId })], status: 201, body: z.looseObject({ eventId: id }), v1: alloc.createSet, + access: 'supervisor', campusScope: 'scopeEvent(body.eventId)', middleware: [cs.scopeEvent({ from: (req: any) => req.body?.eventId })], status: 201, body: z.looseObject({ eventId: id }), documented: { body: D.obj({ eventId: D.str, name: D.str.describe('e.g. Cabins, Buses'), showOnTicket: D.optBool }), response: allocationSet }, v1: alloc.createSet, }); const setScope = cs.scopeEvent({ resolve: 'allocationSet' }); const groupScope = cs.scopeEvent({ resolve: 'allocationGroup' }); -v1Route({ method: 'patch', path: '/allocation-sets/:id', tag: 'Allocations', summary: 'Change a set', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], params: idParams, body: loose, v1: alloc.updateSet }); -v1Route({ method: 'delete', path: '/allocation-sets/:id', tag: 'Allocations', summary: 'Delete a set', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], params: idParams, v1: alloc.deleteSet }); -v1Route({ method: 'get', path: '/allocation-sets/:id/lists', tag: 'Allocations', summary: 'A set\'s lists (who is in each group)', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], params: idParams, query: filters('medical'), v1: alloc.getSetLists }); -v1Route({ method: 'post', path: '/allocation-sets/:id/groups', tag: 'Allocations', summary: 'Add a group', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], status: 201, params: idParams, body: loose, v1: alloc.createGroup }); -v1Route({ method: 'put', path: '/allocation-sets/:id/assignments', tag: 'Allocations', summary: 'Put people in groups', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], params: idParams, body: loose, v1: alloc.assign }); -v1Route({ method: 'delete', path: '/allocation-sets/:id/assignments', tag: 'Allocations', summary: 'Empty every group', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], params: idParams, v1: alloc.clearAssignments }); -v1Route({ method: 'post', path: '/allocation-sets/:id/auto', tag: 'Allocations', summary: 'Fill the groups automatically', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], params: idParams, body: loose, v1: alloc.autoAssign }); -v1Route({ method: 'patch', path: '/allocation-groups/:id', tag: 'Allocations', summary: 'Change a group', access: 'supervisor', campusScope: 'scopeEvent(allocationGroup)', middleware: [groupScope], params: idParams, body: loose, v1: alloc.updateGroup }); -v1Route({ method: 'delete', path: '/allocation-groups/:id', tag: 'Allocations', summary: 'Delete a group', access: 'supervisor', campusScope: 'scopeEvent(allocationGroup)', middleware: [groupScope], params: idParams, v1: alloc.deleteGroup }); +v1Route({ method: 'patch', path: '/allocation-sets/:id', tag: 'Allocations', summary: 'Change a set', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], params: idParams, body: loose, documented: { body: D.obj({ name: D.optStr, showOnTicket: D.optBool }), response: allocationSet }, v1: alloc.updateSet }); +v1Route({ method: 'delete', path: '/allocation-sets/:id', tag: 'Allocations', summary: 'Delete a set', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], params: idParams, documented: { response: D.message }, v1: alloc.deleteSet }); +v1Route({ method: 'get', path: '/allocation-sets/:id/lists', tag: 'Allocations', summary: 'A set\'s lists (who is in each group)', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], params: idParams, query: filters('medical'), documented: { response: D.obj({ set: D.obj({ id: D.str, name: D.str }), event: D.anyObj, groups: z.array(D.obj({ id: D.str, name: D.str, capacity: D.optNum, gender: D.optStr, leader: D.optStr, members: z.array(member) })) }) }, v1: alloc.getSetLists }); +v1Route({ method: 'post', path: '/allocation-sets/:id/groups', tag: 'Allocations', summary: 'Add a group', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], status: 201, params: idParams, body: loose, documented: { body: groupInput, response: group }, v1: alloc.createGroup }); +v1Route({ method: 'put', path: '/allocation-sets/:id/assignments', tag: 'Allocations', summary: 'Put people in groups', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], params: idParams, body: loose, documented: { body: D.obj({ attendeeId: D.str, groupId: D.optStr.describe('null takes them out') }), response: D.message }, v1: alloc.assign }); +v1Route({ method: 'delete', path: '/allocation-sets/:id/assignments', tag: 'Allocations', summary: 'Empty every group', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], params: idParams, documented: { response: D.message }, v1: alloc.clearAssignments }); +v1Route({ method: 'post', path: '/allocation-sets/:id/auto', tag: 'Allocations', summary: 'Fill the groups automatically', access: 'supervisor', campusScope: 'scopeEvent(allocationSet)', middleware: [setScope], params: idParams, body: loose, documented: { body: D.obj({ mode: z.enum(['together', 'split']).optional().describe('Keep each booking together, or spread them') }), response: D.obj({ placed: D.num, unplaced: D.num, message: D.str }) }, v1: alloc.autoAssign }); +v1Route({ method: 'patch', path: '/allocation-groups/:id', tag: 'Allocations', summary: 'Change a group', access: 'supervisor', campusScope: 'scopeEvent(allocationGroup)', middleware: [groupScope], params: idParams, body: loose, documented: { body: groupInput, response: group }, v1: alloc.updateGroup }); +v1Route({ method: 'delete', path: '/allocation-groups/:id', tag: 'Allocations', summary: 'Delete a group', access: 'supervisor', campusScope: 'scopeEvent(allocationGroup)', middleware: [groupScope], params: idParams, documented: { response: D.message }, v1: alloc.deleteGroup }); diff --git a/apps/events/backend/src/v2/resources/corrections.ts b/apps/events/backend/src/v2/resources/corrections.ts new file mode 100644 index 0000000..e1be559 --- /dev/null +++ b/apps/events/backend/src/v2/resources/corrections.ts @@ -0,0 +1,114 @@ +/** + * Corrections (1.52.0): see services/corrections.ts. Admins only, except "Fill in later" for + * staff at the door and in Manual registrations. + */ +import { z } from 'zod'; +import type { Request } from 'express'; +import { defineRoute, type ApiUser } from '../route'; +import { single } from '../paging'; +import { id, idParams } from '../schemas'; +import * as corrections from '../../services/corrections'; + +/* eslint-disable @typescript-eslint/no-explicit-any -- campus scope middleware is JavaScript */ +const campusScope = require('../../utils/campusScope') as { + scopeEvent(opts?: { need?: 'view' | 'manage'; resolve?: string }): any; +}; + +const audit = (req: Request, user: ApiUser | null) => { + const { getClientIp } = require('../../utils/requestUtils') as { getClientIp(req: unknown): string }; + return { actor: { id: user!.id, role: user!.role }, ip: getClientIp(req) }; +}; + +const reason = z.string().trim().max(500).nullish().describe('Why — kept in the audit log'); +const send = z.boolean().optional().describe('Send the new tickets to the attendee (off by default)'); + +const ticketRow = z.object({ + id, + qrCode: z.string(), + label: z.string().describe('Ticket option, variant and (a picked session) the session'), + isMainTicket: z.boolean(), + name: z.string().describe('Who it\'s for'), + quantity: z.number().int(), + sessionIds: z.array(z.string()).describe(`The sessions it covers (\`${corrections.WHOLE_EVENT}\` on a single-date event)`), + checkedIn: z.record(z.string(), z.number().int()).describe('People checked in, per session'), +}); +const registrationRow = z.object({ + id, + status: z.string(), + createdAt: z.coerce.date(), + user: z.object({ id, name: z.string(), email: z.string().nullable(), phoneNumber: z.string().nullable() }), + totalDue: z.number(), + paid: z.number(), + balance: z.number(), + places: z.number().int().describe('Places booked (every line)'), + ticketPlaces: z.number().int().describe('Places with a ticket'), + missingTickets: z.boolean().describe('Paid (or released unpaid) but not every place has a ticket'), + formsNeeded: z.number().int().describe('Attendee forms still holding the tickets back'), + formWaived: z.boolean().describe('The form was left for later'), + ticketsReleased: z.boolean().describe('Tickets issued before it was paid'), + complimentary: z.number().describe('Balance written off'), + tickets: z.array(ticketRow), +}); + +export const eventCorrections = defineRoute({ + method: 'get', path: '/corrections/events/:id', tag: 'Corrections', summary: 'An event\'s registrations, with what needs putting right', + description: 'Every registration that isn\'t cancelled — closed and past events too — with its balance, forms still to fill in, tickets and check-ins.', + access: 'admin', params: idParams, + response: single(z.object({ + event: z.object({ + id, title: z.string(), startDate: z.coerce.date(), endDate: z.coerce.date(), closed: z.boolean(), + formRequired: z.boolean(), sessions: z.array(z.object({ id, label: z.string(), startsAt: z.coerce.date() })), + }), + registrations: z.array(registrationRow), + })), + async handler({ params }) { return { data: await corrections.eventCorrections(params.id) }; }, +}); + +export const issueMissing = defineRoute({ + method: 'post', path: '/corrections/events/:id/issue-missing', tag: 'Corrections', summary: 'Issue every missing ticket at an event', + description: 'For each paid registration (or one released unpaid) without all its tickets. Attendee forms still outstanding are left for later.', + access: 'admin', params: idParams, body: z.object({ send }), + response: single(z.object({ registrations: z.number().int(), tickets: z.number().int(), failed: z.array(z.object({ id, name: z.string(), message: z.string() })) })), + async handler({ params, body, user, req }) { return { data: await corrections.issueMissingTickets(params.id, audit(req, user), body) }; }, +}); + +export const issueTickets = defineRoute({ + method: 'post', path: '/corrections/registrations/:id/tickets', tag: 'Corrections', summary: 'Issue a registration\'s tickets now', + description: '`skipForm` leaves the attendee form for later; `payLater` issues them before it\'s paid (the balance is still owed).', + access: 'admin', params: idParams, + body: z.object({ skipForm: z.boolean().optional(), payLater: z.boolean().optional(), send, reason }), + response: single(z.object({ ticketsIssued: z.number().int(), registration: registrationRow })), + async handler({ params, body, user, req }) { return { data: await corrections.issueTickets(params.id, audit(req, user), body) }; }, +}); + +export const complimentary = defineRoute({ + method: 'post', path: '/corrections/registrations/:id/complimentary', tag: 'Corrections', summary: 'Make it free', + description: 'What\'s still owed is written off as a complimentary discount (income stays what was really paid), it\'s marked paid and its tickets are issued. Not on a closed event.', + access: 'admin', params: idParams, + body: z.object({ skipForm: z.boolean().optional(), send, reason }), + response: single(z.object({ amount: z.number(), ticketsIssued: z.number().int(), registration: registrationRow })), + async handler({ params, body, user, req }) { return { data: await corrections.makeComplimentary(params.id, audit(req, user), body) }; }, +}); + +export const checkIn = defineRoute({ + method: 'post', path: '/corrections/tickets/:id/check-in', tag: 'Corrections', summary: 'Check a ticket in (or undo it) after the fact', + description: 'Any time — after the event or session, or once the event is closed. `present: false` undoes the check-in for that session. Recorded as a manual check-in; no message is sent.', + access: 'admin', params: idParams, + body: z.object({ + sessionId: id.nullish().describe('Multi-day events: the session'), + people: z.number().int().min(1).max(1000).nullish().describe('How many (default: everyone left on the ticket)'), + present: z.boolean().optional().describe('false undoes it'), + reason, + }), + response: single(z.object({ checkedIn: z.number().int(), quantity: z.number().int() })), + async handler({ params, body, user, req }) { return { data: await corrections.correctCheckIn(params.id, audit(req, user), body) }; }, +}); + +export const formLater = defineRoute({ + method: 'post', path: '/registrations/:id/form-later', tag: 'Registrations', summary: 'Fill in the attendee form later', + description: 'At the door: the tickets stop waiting for the required attendee form (issued now if it\'s paid) and the payer is sent a link to fill it in (`notify: false` to not).', + access: 'staff', campusScope: 'scopeEvent(registration)', middleware: [campusScope.scopeEvent({ resolve: 'registration' })], params: idParams, + body: z.object({ notify: z.boolean().optional() }), + response: single(z.object({ ticketsIssued: z.number().int(), sentTo: z.array(z.string()) })), + async handler({ params, body, user, req }) { return { data: await corrections.leaveFormForLater(params.id, audit(req, user), body) }; }, +}); diff --git a/apps/events/backend/src/v2/resources/eventsManage.ts b/apps/events/backend/src/v2/resources/eventsManage.ts index 7c0e2b0..5f045b6 100644 --- a/apps/events/backend/src/v2/resources/eventsManage.ts +++ b/apps/events/backend/src/v2/resources/eventsManage.ts @@ -1,4 +1,5 @@ import { z } from 'zod'; +import * as D from '../docs'; import type { Request } from 'express'; import { defineRoute, type ApiUser } from '../route'; import { single } from '../paging'; @@ -148,6 +149,7 @@ export const copyFrom = defineRoute({ middleware: [campusScope.scopeEvent({ need: 'manage' }), campusScope.scopeBody([['fromEventId', 'event']])], params: idParams, body: z.object({ fromEventId: id }), + documented: { response: D.obj({ sets: D.num.describe('Allocation sets copied'), groups: D.num.describe('Groups copied'), costs: D.num.describe('Costs copied (admins)') }) }, response: single(z.looseObject({})), async handler({ params, body, user }) { return { data: JSON.parse(JSON.stringify(await copySetupFrom(params.id, body.fromEventId, actorOf(user)) ?? {})) }; diff --git a/apps/events/backend/src/v2/resources/kidsVolunteers.ts b/apps/events/backend/src/v2/resources/kidsVolunteers.ts index 55aa732..e54953f 100644 --- a/apps/events/backend/src/v2/resources/kidsVolunteers.ts +++ b/apps/events/backend/src/v2/resources/kidsVolunteers.ts @@ -5,6 +5,7 @@ import { z } from 'zod'; import { id, idParams } from '../schemas'; import { v1Route } from '../viaV1'; +import * as D from '../docs'; /* eslint-disable @typescript-eslint/no-explicit-any -- v1 handlers and middleware are JavaScript */ const cs = require('../../utils/campusScope') as { @@ -22,71 +23,119 @@ const SCOPE_LIST = 'scopeList (the handler filters by listWhere)'; const view = { campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()] }; const manage = { campusScope: 'scopeEvent(manage)', middleware: [cs.scopeEvent({ need: 'manage' })] }; +// ─── Documented shapes (docs.ts) ───────────────────────────────────────────── + +const child = D.obj({ + id: D.str, firstName: D.str, lastName: D.str, name: D.str, dateOfBirth: D.optDate, age: D.optNum, gender: D.optStr, + allergies: D.optStr, hasMedical: D.bool, hasCustody: D.bool.describe('There are custody notes'), + medicalNotes: D.optStr.describe('Only where notes may be shown'), custodyNotes: D.optStr, lastCheckInAt: D.optDate, +}); +const childInput = D.obj({ + firstName: D.str, lastName: D.optStr, dateOfBirth: D.optDate, gender: D.optStr.describe('male or female (anything else: not given)'), + allergies: D.optStr, medicalNotes: D.optStr, custodyNotes: D.optStr.describe('Kept encrypted, like the medical notes'), +}); +const adultInput = D.obj({ name: D.str, phone: D.optStr, relationship: D.optStr }); +const adult = adultInput.extend({ id: D.str }); +const family = D.obj({ + id: D.str, name: D.str, + parents: z.array(D.obj({ userId: D.str, name: D.str, phone: D.optStr, email: D.optStr })), + children: z.array(child), adults: z.array(adult).describe('Others who may collect the children'), +}); +const myFamily = D.obj({ + family: family.nullable(), qrToken: D.optStr.describe('The family QR code (shown at the desk)'), + codes: z.array(D.anyObj).describe('Collection codes for children checked in now'), pages: z.array(D.anyObj).describe('Recent "come to the room" messages'), +}); +const parentInput = D.obj({ name: D.str, email: D.optStr, phone: D.optStr.describe('Email or phone needed: the collection code is sent there') }); +const room = D.obj({ id: D.str, name: D.str, minAge: D.optNum, maxAge: D.optNum, capacity: D.optNum, ratio: D.optNum, order: D.optNum, leaderNames: z.array(D.str).optional(), leaderIds: D.ids.optional() }); +const board = D.obj({ + event: D.anyObj, occasion: D.str.describe('The day or session it\'s for'), sessionId: D.optStr, sessionLabel: D.optStr, + rooms: z.array(room), checkIns: z.array(D.anyObj).describe('Children checked in, with room and code'), +}); +const roleShift = D.obj({ startsAt: D.date, endsAt: D.date, text: D.str, hours: D.num }); +const role = D.obj({ + id: D.str, eventId: D.str, sessionId: D.optStr, sessionLabel: D.optStr, name: D.str, description: D.str, + startsAt: D.optDate, endsAt: D.optDate, shift: roleShift, kidsRoom: D.anyObj.nullish(), order: D.num, past: D.bool, + needed: D.optNum, filled: D.optNum, + mine: D.obj({ slotId: D.str, checkedInAt: D.optDate, swapId: D.optStr }).nullable().describe('My place in it'), + coverNeeded: z.array(D.obj({ swapId: D.str, note: D.str })), + volunteers: z.array(D.obj({ slotId: D.str, userId: D.str, name: D.str, phone: D.optStr, email: D.optStr, assignedBy: D.optStr, checkedInAt: D.optDate, checkedInBy: D.optStr, checkInMethod: D.optStr, swapOpen: D.bool, hasTicket: D.bool })).optional().describe('Staff only'), +}); +const roster = D.obj({ + event: D.anyObj, sessions: z.array(D.obj({ id: D.str, label: D.str, startsAt: D.date, endsAt: D.date })), roles: z.array(role), + totals: D.obj({ needed: D.optNum, filled: D.optNum, fillRate: D.optNum.describe('%') }), +}); +const roleInput = D.obj({ + name: D.str, description: D.optStr, sessionId: D.optStr.describe('A multi-day event: the session'), startsAt: D.optDate, endsAt: D.optDate.describe('Default: the event\'s or session\'s times'), + needed: D.numeric.nullish().describe('How many people'), kidsRoomId: D.optStr.describe('Serving in a kids room: counts as a leader on duty'), order: D.numeric.optional(), +}); +const roleRecord = D.obj({ id: D.str, eventId: D.str, name: D.str, description: D.optStr, sessionId: D.optStr, startsAt: D.optDate, endsAt: D.optDate, needed: D.optNum, kidsRoomId: D.optStr, order: D.num }); +const signedUp = D.obj({ slotId: D.str, ticket: D.bool.describe('A free volunteer ticket was issued') }); + // ─── Kids: my family ───────────────────────────────────────────────────────── -v1Route({ method: 'get', path: '/me/family', tag: 'Kids', summary: 'My family', description: 'Children, the adults who may collect them, and the family QR code.', access: 'user', v1: kids.getMine }); -v1Route({ method: 'post', path: '/me/family', tag: 'Kids', summary: 'Start my family', access: 'user', status: 201, body: loose, v1: kids.createMine }); -v1Route({ method: 'patch', path: '/me/family', tag: 'Kids', summary: 'Rename my family', access: 'user', body: loose, v1: kids.renameMine }); -v1Route({ method: 'delete', path: '/me/family', tag: 'Kids', summary: 'Leave my family', access: 'user', v1: kids.leaveMine }); -v1Route({ method: 'post', path: '/me/family/children', tag: 'Kids', summary: 'Add a child', access: 'user', status: 201, body: loose, v1: kids.saveMyChild }); -v1Route({ method: 'put', path: '/me/family/children/:id', tag: 'Kids', summary: 'Change a child', access: 'user', params: idParams, body: loose, v1: kids.saveMyChild }); -v1Route({ method: 'delete', path: '/me/family/children/:id', tag: 'Kids', summary: 'Remove a child', access: 'user', params: idParams, v1: kids.deleteMyChild }); -v1Route({ method: 'post', path: '/me/family/adults', tag: 'Kids', summary: 'Add an adult who may collect', access: 'user', status: 201, body: loose, v1: kids.saveMyAdult }); -v1Route({ method: 'put', path: '/me/family/adults/:id', tag: 'Kids', summary: 'Change an adult', access: 'user', params: idParams, body: loose, v1: kids.saveMyAdult }); -v1Route({ method: 'delete', path: '/me/family/adults/:id', tag: 'Kids', summary: 'Remove an adult', access: 'user', params: idParams, v1: kids.deleteMyAdult }); +v1Route({ method: 'get', path: '/me/family', tag: 'Kids', summary: 'My family', description: 'Children, the adults who may collect them, and the family QR code.', access: 'user', documented: { response: myFamily }, v1: kids.getMine }); +v1Route({ method: 'post', path: '/me/family', tag: 'Kids', summary: 'Start my family', access: 'user', status: 201, body: loose, documented: { body: D.obj({ name: D.optStr }), response: myFamily }, v1: kids.createMine }); +v1Route({ method: 'patch', path: '/me/family', tag: 'Kids', summary: 'Rename my family', access: 'user', body: loose, documented: { body: D.obj({ name: D.str }), response: family }, v1: kids.renameMine }); +v1Route({ method: 'delete', path: '/me/family', tag: 'Kids', summary: 'Leave my family', access: 'user', documented: { response: D.anyObj.describe('What happened: left, or the family was deleted as the last parent') }, v1: kids.leaveMine }); +v1Route({ method: 'post', path: '/me/family/children', tag: 'Kids', summary: 'Add a child', access: 'user', status: 201, body: loose, documented: { body: childInput, response: child }, v1: kids.saveMyChild }); +v1Route({ method: 'put', path: '/me/family/children/:id', tag: 'Kids', summary: 'Change a child', access: 'user', params: idParams, body: loose, documented: { body: childInput.partial(), response: child }, v1: kids.saveMyChild }); +v1Route({ method: 'delete', path: '/me/family/children/:id', tag: 'Kids', summary: 'Remove a child', access: 'user', params: idParams, documented: { response: D.message }, v1: kids.deleteMyChild }); +v1Route({ method: 'post', path: '/me/family/adults', tag: 'Kids', summary: 'Add an adult who may collect', access: 'user', status: 201, body: loose, documented: { body: adultInput, response: adult }, v1: kids.saveMyAdult }); +v1Route({ method: 'put', path: '/me/family/adults/:id', tag: 'Kids', summary: 'Change an adult', access: 'user', params: idParams, body: loose, documented: { body: adultInput, response: adult }, v1: kids.saveMyAdult }); +v1Route({ method: 'delete', path: '/me/family/adults/:id', tag: 'Kids', summary: 'Remove an adult', access: 'user', params: idParams, documented: { response: D.message }, v1: kids.deleteMyAdult }); // ─── Kids: set-up and the check-in desk ────────────────────────────────────── -v1Route({ method: 'get', path: '/kids/setup-events', tag: 'Kids', summary: 'Events that can have kids check-in', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], v1: kids.setupEvents }); -v1Route({ method: 'get', path: '/kids/events', tag: 'Kids', summary: 'Events with kids check-in', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], v1: kids.listEvents }); -v1Route({ method: 'get', path: '/events/:id/kids/settings', tag: 'Kids', summary: 'An event\'s kids check-in set-up', access: 'supervisor', ...view, params: idParams, map: asEvent, v1: kids.getSettings }); -v1Route({ method: 'put', path: '/events/:id/kids/settings', tag: 'Kids', summary: 'Set up kids check-in', access: 'supervisor', ...manage, params: idParams, body: loose, map: asEvent, v1: kids.saveSettings }); -v1Route({ method: 'get', path: '/events/:id/kids/board', tag: 'Kids', summary: 'Who is checked in, by room', access: 'staff', ...view, params: idParams, query: filters('sessionId', 'log'), map: asEvent, v1: kids.getBoard }); -v1Route({ method: 'get', path: '/events/:id/kids/families', tag: 'Kids', summary: 'Find a family', access: 'staff', ...view, params: idParams, query: filters('q', 'sessionId'), map: asEvent, v1: kids.searchFamilies }); -v1Route({ method: 'post', path: '/events/:id/kids/families', tag: 'Kids', summary: 'Register a family at the desk', access: 'staff', ...view, status: 201, params: idParams, body: loose, map: asEvent, v1: kids.createFamilyAtDesk }); -v1Route({ method: 'get', path: '/events/:id/kids/families/qr/:token', tag: 'Kids', summary: 'The family for a QR code', access: 'staff', ...view, params: z.object({ id, token: z.string().min(1).max(200) }), map: asEvent, v1: kids.familyByQr }); +v1Route({ method: 'get', path: '/kids/setup-events', tag: 'Kids', summary: 'Events that can have kids check-in', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], documented: { response: z.array(D.event.partial().extend({ kidsCheckIn: D.optBool })) }, v1: kids.setupEvents }); +v1Route({ method: 'get', path: '/kids/events', tag: 'Kids', summary: 'Events with kids check-in', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], documented: { response: z.array(D.event.partial()) }, v1: kids.listEvents }); +v1Route({ method: 'get', path: '/events/:id/kids/settings', tag: 'Kids', summary: 'An event\'s kids check-in set-up', access: 'supervisor', ...view, params: idParams, map: asEvent, documented: { response: D.obj({ event: D.obj({ id: D.str, title: D.str, scheduleType: D.optStr, kidsCheckIn: D.bool, kidsOptionId: D.optStr, kidsRoomSetId: D.optStr }), options: z.array(D.eventOption.partial()), sets: z.array(D.anyObj).describe('Allocation sets that can be the rooms') }) }, v1: kids.getSettings }); +v1Route({ method: 'put', path: '/events/:id/kids/settings', tag: 'Kids', summary: 'Set up kids check-in', access: 'supervisor', ...manage, params: idParams, body: loose, map: asEvent, documented: { body: D.obj({ enabled: D.optBool, optionId: D.optStr.describe('The kids ticket (`new` makes a free one; null: none)'), roomSetId: D.optStr.describe('The allocation set used as rooms') }).describe('Only what changes'), response: D.anyObj.describe('The saved set-up, as GET answers') }, v1: kids.saveSettings }); +v1Route({ method: 'get', path: '/events/:id/kids/board', tag: 'Kids', summary: 'Who is checked in, by room', access: 'staff', ...view, params: idParams, query: filters('sessionId', 'log'), map: asEvent, documented: { response: board }, v1: kids.getBoard }); +v1Route({ method: 'get', path: '/events/:id/kids/families', tag: 'Kids', summary: 'Find a family', access: 'staff', ...view, params: idParams, query: filters('q', 'sessionId'), map: asEvent, documented: { response: z.array(family) }, v1: kids.searchFamilies }); +v1Route({ method: 'post', path: '/events/:id/kids/families', tag: 'Kids', summary: 'Register a family at the desk', access: 'staff', ...view, status: 201, params: idParams, body: loose, map: asEvent, documented: { body: D.obj({ name: D.optStr, parent: parentInput, children: z.array(childInput).max(12).optional() }), response: family }, v1: kids.createFamilyAtDesk }); +v1Route({ method: 'get', path: '/events/:id/kids/families/qr/:token', tag: 'Kids', summary: 'The family for a QR code', access: 'staff', ...view, params: z.object({ id, token: z.string().min(1).max(200) }), map: asEvent, documented: { response: family }, v1: kids.familyByQr }); const familyParams = z.object({ id, familyId: id }); -v1Route({ method: 'get', path: '/events/:id/kids/families/:familyId', tag: 'Kids', summary: 'One family', access: 'staff', ...view, params: familyParams, map: asEvent, v1: kids.getFamily }); -v1Route({ method: 'post', path: '/events/:id/kids/families/:familyId/parents', tag: 'Kids', summary: 'Add a parent at the desk', access: 'staff', ...view, status: 201, params: familyParams, body: loose, map: asEvent, v1: kids.addParentAtDesk }); -v1Route({ method: 'post', path: '/events/:id/kids/families/:familyId/children', tag: 'Kids', summary: 'Add a child at the desk', access: 'staff', ...view, status: 201, params: familyParams, body: loose, map: asEvent, v1: kids.saveChildAtDesk }); -v1Route({ method: 'put', path: '/events/:id/kids/families/:familyId/children/:childId', tag: 'Kids', summary: 'Change a child at the desk', access: 'staff', ...view, params: z.object({ id, familyId: id, childId: id }), body: loose, map: asEvent, v1: kids.saveChildAtDesk }); -v1Route({ method: 'post', path: '/events/:id/kids/families/:familyId/adults', tag: 'Kids', summary: 'Add an adult at the desk', access: 'staff', ...view, status: 201, params: familyParams, body: loose, map: asEvent, v1: kids.addAdultAtDesk }); -v1Route({ method: 'post', path: '/events/:id/kids/check-in', tag: 'Kids', summary: 'Check children in', description: 'Answers the collection code and labels to print.', access: 'staff', ...view, params: idParams, body: loose, map: asEvent, v1: kids.checkIn }); -v1Route({ method: 'post', path: '/events/:id/kids/check-out', tag: 'Kids', summary: 'Check children out', description: 'With the collection code; refused for someone not allowed to collect.', access: 'staff', ...view, params: idParams, body: loose, map: asEvent, v1: kids.checkOut }); -v1Route({ method: 'get', path: '/events/:id/kids/code/:code', tag: 'Kids', summary: 'Who a collection code is for', access: 'staff', ...view, params: z.object({ id, code: z.string().min(1).max(40) }), query: filters('sessionId'), map: asEvent, v1: kids.lookupCode }); -v1Route({ method: 'post', path: '/events/:id/kids/duty', tag: 'Kids', summary: 'Say which room I\'m on', access: 'staff', ...view, params: idParams, body: loose, map: asEvent, v1: kids.setDuty }); -v1Route({ method: 'get', path: '/events/:id/kids/offline', tag: 'Kids', summary: 'Everything the desk needs offline', access: 'staff', ...view, params: idParams, query: filters('deviceId', 'sessionId'), map: asEvent, v1: kids.offlineSnapshot }); -v1Route({ method: 'post', path: '/events/:id/kids/sync', tag: 'Kids', summary: 'Upload check-ins made offline', access: 'staff', ...view, params: idParams, body: loose, map: asEvent, v1: kids.syncOffline }); +v1Route({ method: 'get', path: '/events/:id/kids/families/:familyId', tag: 'Kids', summary: 'One family', access: 'staff', ...view, params: familyParams, map: asEvent, documented: { response: family }, v1: kids.getFamily }); +v1Route({ method: 'post', path: '/events/:id/kids/families/:familyId/parents', tag: 'Kids', summary: 'Add a parent at the desk', access: 'staff', ...view, status: 201, params: familyParams, body: loose, map: asEvent, documented: { body: parentInput, response: family }, v1: kids.addParentAtDesk }); +v1Route({ method: 'post', path: '/events/:id/kids/families/:familyId/children', tag: 'Kids', summary: 'Add a child at the desk', access: 'staff', ...view, status: 201, params: familyParams, body: loose, map: asEvent, documented: { body: childInput, response: child }, v1: kids.saveChildAtDesk }); +v1Route({ method: 'put', path: '/events/:id/kids/families/:familyId/children/:childId', tag: 'Kids', summary: 'Change a child at the desk', access: 'staff', ...view, params: z.object({ id, familyId: id, childId: id }), body: loose, map: asEvent, documented: { body: childInput.partial(), response: child }, v1: kids.saveChildAtDesk }); +v1Route({ method: 'post', path: '/events/:id/kids/families/:familyId/adults', tag: 'Kids', summary: 'Add an adult at the desk', access: 'staff', ...view, status: 201, params: familyParams, body: loose, map: asEvent, documented: { body: adultInput, response: family }, v1: kids.addAdultAtDesk }); +v1Route({ method: 'post', path: '/events/:id/kids/check-in', tag: 'Kids', summary: 'Check children in', description: 'Answers the collection code and labels to print.', access: 'staff', ...view, params: idParams, body: loose, map: asEvent, documented: { body: D.obj({ familyId: D.str, sessionId: D.optStr, children: z.array(D.obj({ childId: D.str, roomId: D.optStr })).describe('Who, and into which room (default: by age)'), sendToAdultId: D.optStr.describe('Send the code to this adult too') }), response: D.obj({ code: D.str.describe('The collection code'), qr: D.str, occasion: D.str, family: D.obj({ id: D.str, name: D.str }), checkIns: z.array(D.obj({ id: D.str, name: D.str, firstName: D.str, room: D.anyObj.nullish(), already: D.bool, sticker: D.optStr.describe('Write this on the sticker') })) }) }, v1: kids.checkIn }); +v1Route({ method: 'post', path: '/events/:id/kids/check-out', tag: 'Kids', summary: 'Check children out', description: 'With the collection code; refused for someone not allowed to collect.', access: 'staff', ...view, params: idParams, body: loose, map: asEvent, documented: { body: D.obj({ code: D.str, checkInIds: D.ids.optional().describe('Just these children (default: all on the code)'), collectedBy: D.optStr.describe('Who collected them'), roomId: D.optStr, sessionId: D.optStr }), response: D.obj({ checkedOut: z.array(D.obj({ id: D.str, name: D.str, room: D.optStr })) }) }, v1: kids.checkOut }); +v1Route({ method: 'get', path: '/events/:id/kids/code/:code', tag: 'Kids', summary: 'Who a collection code is for', access: 'staff', ...view, params: z.object({ id, code: z.string().min(1).max(40) }), query: filters('sessionId'), map: asEvent, documented: { response: D.obj({ code: D.str, found: D.bool, family: D.anyObj.nullish(), children: z.array(D.obj({ id: D.str, name: D.str, room: D.anyObj.nullish(), checkedOutAt: D.optDate, collectedBy: D.optStr })) }) }, v1: kids.lookupCode }); +v1Route({ method: 'post', path: '/events/:id/kids/duty', tag: 'Kids', summary: 'Say which room I\'m on', access: 'staff', ...view, params: idParams, body: loose, map: asEvent, documented: { body: D.obj({ roomId: D.str, sessionId: D.optStr, on: D.optBool.describe('false: off duty') }), response: D.obj({ roomId: D.str, on: D.bool }) }, v1: kids.setDuty }); +v1Route({ method: 'get', path: '/events/:id/kids/offline', tag: 'Kids', summary: 'Everything the desk needs offline', access: 'staff', ...view, params: idParams, query: filters('deviceId', 'sessionId'), map: asEvent, documented: { response: board.extend({ families: z.array(family), codes: z.array(D.anyObj).describe('Codes reserved for this device'), downloadedAt: D.date }) }, v1: kids.offlineSnapshot }); +v1Route({ method: 'post', path: '/events/:id/kids/sync', tag: 'Kids', summary: 'Upload check-ins made offline', access: 'staff', ...view, params: idParams, body: loose, map: asEvent, documented: { body: D.obj({ deviceId: D.str, sessionId: D.optStr, checkIns: z.array(D.anyObj).optional(), checkOuts: z.array(D.anyObj).optional() }), response: D.obj({ checkedIn: D.num, checkedOut: D.num, conflicts: z.array(D.anyObj) }) }, v1: kids.syncOffline }); const checkInScope = { campusScope: 'scopeEvent(kidsCheckIn)', middleware: [cs.scopeEvent({ resolve: 'kidsCheckIn' })] }; -v1Route({ method: 'post', path: '/kids/check-ins/:id/override', tag: 'Kids', summary: 'Let someone not on the list collect', description: 'Logged, with the reason.', access: 'staff', ...checkInScope, params: idParams, body: loose, v1: kids.overrideCheckOut }); -v1Route({ method: 'post', path: '/kids/check-ins/:id/page', tag: 'Kids', summary: 'Page a child\'s parent', access: 'staff', ...checkInScope, params: idParams, body: loose, v1: kids.pageParent }); -v1Route({ method: 'put', path: '/kids/check-ins/:id/room', tag: 'Kids', summary: 'Move a child to another room', access: 'staff', ...checkInScope, params: idParams, body: loose, v1: kids.moveRoom }); -v1Route({ method: 'post', path: '/kids/alerts/:id/resolve', tag: 'Kids', summary: 'Resolve an alert', access: 'staff', campusScope: 'scopeEvent(kidsAlert)', middleware: [cs.scopeEvent({ resolve: 'kidsAlert' })], params: idParams, body: loose, v1: kids.resolveAlert }); +v1Route({ method: 'post', path: '/kids/check-ins/:id/override', tag: 'Kids', summary: 'Let someone not on the list collect', description: 'Logged, with the reason.', access: 'staff', ...checkInScope, params: idParams, body: loose, documented: { body: D.obj({ reason: D.str, collectedBy: D.str }), response: D.obj({ id: D.str, checkedOutAt: D.date }) }, v1: kids.overrideCheckOut }); +v1Route({ method: 'post', path: '/kids/check-ins/:id/page', tag: 'Kids', summary: 'Page a child\'s parent', access: 'staff', ...checkInScope, params: idParams, body: loose, documented: { body: D.obj({ message: D.optStr }), response: D.obj({ sent: z.array(D.str).describe('Channels used'), text: D.str }) }, v1: kids.pageParent }); +v1Route({ method: 'put', path: '/kids/check-ins/:id/room', tag: 'Kids', summary: 'Move a child to another room', access: 'staff', ...checkInScope, params: idParams, body: loose, documented: { body: D.obj({ roomId: D.str }), response: D.obj({ id: D.str, roomId: D.str }) }, v1: kids.moveRoom }); +v1Route({ method: 'post', path: '/kids/alerts/:id/resolve', tag: 'Kids', summary: 'Resolve an alert', access: 'staff', campusScope: 'scopeEvent(kidsAlert)', middleware: [cs.scopeEvent({ resolve: 'kidsAlert' })], params: idParams, body: loose, documented: { response: D.obj({ resolved: D.num }) }, v1: kids.resolveAlert }); // ─── Volunteering: mine ────────────────────────────────────────────────────── -v1Route({ method: 'get', path: '/me/volunteering', tag: 'Volunteers', summary: 'Where I\'m serving', access: 'user', v1: vol.getMine }); -v1Route({ method: 'get', path: '/events/:id/volunteer-roles', tag: 'Volunteers', summary: 'Roles I can serve in at an event', access: 'user', params: idParams, map: asEvent, v1: vol.getEventRoles }); -v1Route({ method: 'post', path: '/volunteer-roles/:id/sign-up', tag: 'Volunteers', summary: 'Sign up to serve', access: 'user', status: 201, params: idParams, body: loose, v1: vol.signUp }); -v1Route({ method: 'delete', path: '/volunteer-slots/:id', tag: 'Volunteers', summary: 'Stop serving in a slot', access: 'user', params: idParams, v1: vol.withdraw }); -v1Route({ method: 'post', path: '/volunteer-slots/:id/swap', tag: 'Volunteers', summary: 'Ask someone to take my slot', access: 'user', params: idParams, body: loose, v1: vol.requestSwap }); -v1Route({ method: 'delete', path: '/volunteer-swaps/:id', tag: 'Volunteers', summary: 'Cancel a swap request', access: 'user', params: idParams, v1: vol.cancelSwap }); -v1Route({ method: 'post', path: '/volunteer-swaps/:id/accept', tag: 'Volunteers', summary: 'Take someone\'s slot', access: 'user', params: idParams, body: loose, v1: vol.acceptSwap }); -v1Route({ method: 'post', path: '/volunteering/check-in', tag: 'Volunteers', summary: 'Check myself in (the event\'s QR code)', access: 'user', body: loose, v1: vol.checkIn }); +v1Route({ method: 'get', path: '/me/volunteering', tag: 'Volunteers', summary: 'Where I\'m serving', access: 'user', documented: { response: D.obj({ slots: z.array(D.obj({ slotId: D.str, role: D.anyObj, event: D.anyObj, shift: roleShift, checkedInAt: D.optDate, canCheckIn: D.bool, past: D.bool, swapId: D.optStr, hasTicket: D.bool })), cover: z.array(D.anyObj).describe('Slots others want covered'), events: z.array(D.obj({ id: D.str, title: D.str, startDate: D.date, endDate: D.date, location: D.optStr, roles: D.num })) }) }, v1: vol.getMine }); +v1Route({ method: 'get', path: '/events/:id/volunteer-roles', tag: 'Volunteers', summary: 'Roles I can serve in at an event', access: 'user', params: idParams, map: asEvent, documented: { response: roster }, v1: vol.getEventRoles }); +v1Route({ method: 'post', path: '/volunteer-roles/:id/sign-up', tag: 'Volunteers', summary: 'Sign up to serve', access: 'user', status: 201, params: idParams, body: loose, documented: { response: signedUp }, v1: vol.signUp }); +v1Route({ method: 'delete', path: '/volunteer-slots/:id', tag: 'Volunteers', summary: 'Stop serving in a slot', access: 'user', params: idParams, documented: { response: D.message }, v1: vol.withdraw }); +v1Route({ method: 'post', path: '/volunteer-slots/:id/swap', tag: 'Volunteers', summary: 'Ask someone to take my slot', access: 'user', params: idParams, body: loose, documented: { body: D.obj({ note: D.optStr }), response: D.obj({ swapId: D.str }) }, v1: vol.requestSwap }); +v1Route({ method: 'delete', path: '/volunteer-swaps/:id', tag: 'Volunteers', summary: 'Cancel a swap request', access: 'user', params: idParams, documented: { response: D.obj({ cancelled: z.literal(true) }) }, v1: vol.cancelSwap }); +v1Route({ method: 'post', path: '/volunteer-swaps/:id/accept', tag: 'Volunteers', summary: 'Take someone\'s slot', access: 'user', params: idParams, body: loose, documented: { response: D.obj({ slotId: D.str, role: D.str, event: D.str }) }, v1: vol.acceptSwap }); +v1Route({ method: 'post', path: '/volunteering/check-in', tag: 'Volunteers', summary: 'Check myself in (the event\'s QR code)', access: 'user', body: loose, documented: { body: D.obj({ qr: D.str.describe('What the QR code holds') }), response: D.obj({ event: D.obj({ id: D.str, title: D.str }), checkedIn: z.array(D.obj({ role: D.str, kidsRoom: D.optStr })), already: z.array(D.str) }) }, v1: vol.checkIn }); // ─── Volunteering: rosters ─────────────────────────────────────────────────── -v1Route({ method: 'get', path: '/volunteering/events', tag: 'Volunteers', summary: 'Events with volunteer roles', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('all'), v1: vol.listEvents }); -v1Route({ method: 'get', path: '/volunteering/hours', tag: 'Volunteers', summary: 'Hours served', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('from', 'to', 'eventId'), v1: vol.hours }); -v1Route({ method: 'get', path: '/events/:id/volunteers', tag: 'Volunteers', summary: 'An event\'s roster', access: 'staff', ...view, params: idParams, query: filters('log'), map: asEvent, v1: vol.getRoster }); -v1Route({ method: 'get', path: '/events/:id/volunteers/qr', tag: 'Volunteers', summary: 'The self check-in QR code', access: 'staff', ...view, params: idParams, map: asEvent, v1: vol.getQr }); -v1Route({ method: 'get', path: '/events/:id/volunteers/settings', tag: 'Volunteers', summary: 'Volunteer set-up', access: 'supervisor', ...view, params: idParams, map: asEvent, v1: vol.getSettings }); -v1Route({ method: 'put', path: '/events/:id/volunteers/settings', tag: 'Volunteers', summary: 'Set up volunteering', access: 'supervisor', ...manage, params: idParams, body: loose, map: asEvent, v1: vol.saveSettings }); -v1Route({ method: 'post', path: '/events/:id/volunteer-roles', tag: 'Volunteers', summary: 'Add a role', access: 'supervisor', ...manage, status: 201, params: idParams, body: loose, map: asEvent, v1: vol.createRole }); +v1Route({ method: 'get', path: '/volunteering/events', tag: 'Volunteers', summary: 'Events with volunteer roles', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('all'), documented: { response: z.array(D.obj({ id: D.str, title: D.str, startDate: D.date, endDate: D.date, scheduleType: D.optStr, campusId: D.optStr, roles: D.num })) }, v1: vol.listEvents }); +v1Route({ method: 'get', path: '/volunteering/hours', tag: 'Volunteers', summary: 'Hours served', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('from', 'to', 'eventId'), documented: { response: z.array(D.obj({ userId: D.str.optional(), name: D.str, hours: D.num, shifts: D.optNum })) }, v1: vol.hours }); +v1Route({ method: 'get', path: '/events/:id/volunteers', tag: 'Volunteers', summary: 'An event\'s roster', access: 'staff', ...view, params: idParams, query: filters('log'), map: asEvent, documented: { response: roster }, v1: vol.getRoster }); +v1Route({ method: 'get', path: '/events/:id/volunteers/qr', tag: 'Volunteers', summary: 'The self check-in QR code', access: 'staff', ...view, params: idParams, map: asEvent, documented: { response: D.obj({ token: D.str, qr: D.str.describe('Put this in the QR code') }) }, v1: vol.getQr }); +v1Route({ method: 'get', path: '/events/:id/volunteers/settings', tag: 'Volunteers', summary: 'Volunteer set-up', access: 'supervisor', ...view, params: idParams, map: asEvent, documented: { response: D.obj({ event: D.obj({ id: D.str, title: D.str, volunteerOptionId: D.optStr }), options: z.array(D.eventOption.partial()), kidsRooms: z.array(D.anyObj) }) }, v1: vol.getSettings }); +v1Route({ method: 'put', path: '/events/:id/volunteers/settings', tag: 'Volunteers', summary: 'Set up volunteering', access: 'supervisor', ...manage, params: idParams, body: loose, map: asEvent, documented: { body: D.obj({ optionId: D.optStr.describe('The free volunteer ticket (null: none)') }), response: D.anyObj.describe('The saved set-up, as GET answers') }, v1: vol.saveSettings }); +v1Route({ method: 'post', path: '/events/:id/volunteer-roles', tag: 'Volunteers', summary: 'Add a role', access: 'supervisor', ...manage, status: 201, params: idParams, body: loose, map: asEvent, documented: { body: roleInput, response: roleRecord }, v1: vol.createRole }); const roleManage = { campusScope: 'scopeEvent(servingRole, manage)', middleware: [cs.scopeEvent({ resolve: 'servingRole', need: 'manage' })] }; -v1Route({ method: 'patch', path: '/volunteer-roles/:id', tag: 'Volunteers', summary: 'Change a role', access: 'supervisor', ...roleManage, params: idParams, body: loose, v1: vol.updateRole }); -v1Route({ method: 'delete', path: '/volunteer-roles/:id', tag: 'Volunteers', summary: 'Delete a role', access: 'supervisor', ...roleManage, params: idParams, v1: vol.deleteRole }); -v1Route({ method: 'post', path: '/volunteer-roles/:id/assign', tag: 'Volunteers', summary: 'Put someone in a role', access: 'supervisor', campusScope: 'scopeEvent(servingRole)', middleware: [cs.scopeEvent({ resolve: 'servingRole' })], params: idParams, body: loose, v1: vol.assign }); +v1Route({ method: 'patch', path: '/volunteer-roles/:id', tag: 'Volunteers', summary: 'Change a role', access: 'supervisor', ...roleManage, params: idParams, body: loose, documented: { body: roleInput.partial(), response: roleRecord }, v1: vol.updateRole }); +v1Route({ method: 'delete', path: '/volunteer-roles/:id', tag: 'Volunteers', summary: 'Delete a role', access: 'supervisor', ...roleManage, params: idParams, documented: { response: D.obj({ message: D.str, volunteers: D.num.describe('People who were in it (told by message)') }) }, v1: vol.deleteRole }); +v1Route({ method: 'post', path: '/volunteer-roles/:id/assign', tag: 'Volunteers', summary: 'Put someone in a role', access: 'supervisor', campusScope: 'scopeEvent(servingRole)', middleware: [cs.scopeEvent({ resolve: 'servingRole' })], params: idParams, body: loose, documented: { body: D.obj({ userId: D.str }), response: signedUp }, v1: vol.assign }); const slotScope = { campusScope: 'scopeEvent(volunteerSlot)', middleware: [cs.scopeEvent({ resolve: 'volunteerSlot' })] }; -v1Route({ method: 'post', path: '/volunteer-slots/:id/check-in', tag: 'Volunteers', summary: 'Check a volunteer in', access: 'staff', ...slotScope, params: idParams, body: loose, v1: vol.checkInManual }); -v1Route({ method: 'post', path: '/volunteer-slots/:id/remove', tag: 'Volunteers', summary: 'Take someone off a slot', access: 'supervisor', ...slotScope, params: idParams, body: loose, v1: vol.remove }); +v1Route({ method: 'post', path: '/volunteer-slots/:id/check-in', tag: 'Volunteers', summary: 'Check a volunteer in', access: 'staff', ...slotScope, params: idParams, body: loose, documented: { body: D.obj({ undo: D.optBool }), response: D.obj({ slotId: D.str, changed: D.bool }) }, v1: vol.checkInManual }); +v1Route({ method: 'post', path: '/volunteer-slots/:id/remove', tag: 'Volunteers', summary: 'Take someone off a slot', access: 'supervisor', ...slotScope, params: idParams, body: loose, documented: { response: D.message }, v1: vol.remove }); diff --git a/apps/events/backend/src/v2/resources/money.ts b/apps/events/backend/src/v2/resources/money.ts index 4901dd1..b9b627d 100644 --- a/apps/events/backend/src/v2/resources/money.ts +++ b/apps/events/backend/src/v2/resources/money.ts @@ -6,6 +6,7 @@ import { z } from 'zod'; import { id, idParams } from '../schemas'; import { listData, v1Route } from '../viaV1'; +import * as D from '../docs'; /* eslint-disable @typescript-eslint/no-explicit-any -- v1 handlers and middleware are JavaScript */ const rateLimit = require('express-rate-limit') as (opts: object) => any; @@ -33,38 +34,88 @@ const asEvent = (ctx: any) => ({ params: { ...ctx.req.params, eventId: ctx.param // Links in messages are credentials, so guessing stays slow (as on v1). const linkLimiter = () => rateLimit({ windowMs: 60 * 1000, max: 30, message: { message: 'Too many attempts. Please try again in a minute.' } }); const SCOPE_LIST = 'scopeList (the handler filters by listWhere)'; + +// ─── Documented shapes (docs.ts) ───────────────────────────────────────────── + +const providerRow = D.obj({ id: D.str.describe('yoco, payfast'), label: D.str }); +const providerSettings = D.obj({ + id: D.str, label: D.str, enabled: D.bool, configured: D.bool.describe('Its keys are set up'), + capabilities: D.anyObj.describe('What the provider can do, e.g. look payments up'), +}); +const openCheckout = D.obj({ + id: D.str, provider: D.str, providerLabel: D.str, canCheck: D.bool.describe('The provider can be asked whether it was paid'), + amount: D.rand, description: D.str, type: D.optStr.describe('registration, donation, sponsorship, season_pass…'), + registrationId: D.optStr, payer: D.optStr, createdAt: D.date, +}); +const payPage = D.obj({ + id: D.str, status: z.enum(['open', 'paid']), amount: D.rand, description: D.str, + provider: D.optStr.describe('The provider already chosen, if any'), providers: z.array(providerRow), cancelUrl: D.optStr, + redirectUrl: D.optStr, form: D.anyObj.nullish().describe('A signed form to post (PayFast)'), +}); +const paymentFull = D.payment.extend({ + registration: D.registration.nullish(), + generatedTickets: z.array(D.ticket).optional().describe('Tickets issued because this paid it in full'), + formsNeeded: D.optNum.describe('Attendee forms still holding the tickets back (1.52.0)'), + donationSplit: D.payment.optional().describe('What was paid over the balance, kept as a donation'), +}); +const cashupLineInput = D.obj({ + method: D.str.describe('cash, card, eft…'), + bankAmount: D.optRand, onHandAmount: D.optRand.describe('Cash only'), pendingAmount: D.optRand.describe('Not cash'), pendingReference: D.optStr, + writeOffs: z.array(D.obj({ category: D.str, amount: D.optRand, reason: D.optStr })).optional(), notes: D.optStr, +}); +const cashupRecord = D.obj({ id: D.str, eventId: D.str, action: D.optStr.describe('close, quick_close, reopen'), notes: D.optStr, createdAt: D.date, performedBy: D.userRef.nullish() }); +const providerTransaction = D.obj({ + id: D.str, provider: D.str, providerLabel: D.str, externalId: D.str.describe('The provider\'s id'), + amount: D.optNum.describe('Cents'), currency: D.optStr, createdDate: D.optDate, checkoutId: D.optStr, methodType: D.optStr, + reconciled: D.bool, ignored: D.bool, paymentId: D.optStr, note: D.optStr.describe('Why it needs a look'), metadata: D.anyObj.nullish(), +}); +const txAnswer = (data: T) => D.obj({ success: D.bool, data, message: D.optStr }); +const waitlistEntry = D.obj({ + id: D.str, eventId: D.str, eventOptionId: D.str, variantId: D.optStr, sessionId: D.optStr, userId: D.str, + quantity: D.num, position: D.num.describe('Place in the queue'), status: D.str.describe('waiting, offered, claimed, expired, removed, left'), + offeredQuantity: D.optNum, offeredAt: D.optDate, offerExpiresAt: D.optDate, claimedAt: D.optDate, registrationId: D.optStr, createdAt: D.date, +}); +const consentRow = D.obj({ + name: D.str.describe('The young person'), status: D.str.describe('not_requested, pending, given, declined'), + parentName: D.optStr, parentEmail: D.optStr, parentPhone: D.optStr, request: D.anyObj.nullish(), +}); +const feedbackField = D.obj({ id: D.str.optional(), type: D.str.describe('rating, multiple_choice, text, yes_no…'), label: D.str, isRequired: D.optBool, helpText: D.optStr, options: z.array(D.str).nullish() }); +const feedbackForm = D.obj({ + id: D.str, eventId: D.str, sendAt: D.optDate, sentAt: D.optDate, audience: D.str.describe('checked_in or everyone'), anonymous: D.bool, intro: D.optStr, + fields: z.array(feedbackField), invited: D.optNum, responses: z.unknown().optional().describe('Answers per question'), +}).nullable().describe('null when the event has no feedback form'); const UNSCOPED = 'unscopedOnly (admins and unscoped supervisors)'; // ─── Payments ──────────────────────────────────────────────────────────────── v1Route({ method: 'get', path: '/payments/providers', tag: 'Payments', summary: 'The payment providers switched on', - access: 'public', v1: providers.listPaymentProviders, + access: 'public', documented: { response: D.obj({ providers: z.array(providerRow), minimumAmount: D.rand.describe('Smallest online payment') }) }, v1: providers.listPaymentProviders, }); v1Route({ method: 'get', path: '/payments/providers/settings', tag: 'Payments', summary: 'Payment provider settings', - description: 'Admins. Keys are masked.', access: 'admin', v1: providers.getPaymentProviderSettings, + description: 'Admins. Keys are masked.', access: 'admin', documented: { response: D.obj({ providers: z.array(providerSettings), minimumAmount: D.rand }) }, v1: providers.getPaymentProviderSettings, }); v1Route({ method: 'put', path: '/payments/providers/settings', tag: 'Payments', summary: 'Change payment provider settings', - access: 'admin', body: z.looseObject({}), v1: providers.updatePaymentProviderSettings, + access: 'admin', body: z.looseObject({}), documented: { body: D.obj({ providers: z.array(D.obj({ id: D.str, enabled: D.bool })).min(1).describe('Every provider, in the order to offer them') }), response: D.obj({ message: D.str, providers: z.array(providerSettings) }) }, v1: providers.updatePaymentProviderSettings, }); v1Route({ method: 'get', path: '/payments/open-checkouts', tag: 'Payments', summary: 'Checkouts started but not finished', - access: 'supervisor', campusScope: UNSCOPED, middleware: [cs.unscopedOnly], v1: providers.listOpenCheckouts, + access: 'supervisor', campusScope: UNSCOPED, middleware: [cs.unscopedOnly], documented: { response: D.obj({ checkouts: z.array(openCheckout), days: D.num.describe('How far back it looks') }) }, v1: providers.listOpenCheckouts, }); v1Route({ method: 'post', path: '/payments/open-checkouts/check', tag: 'Payments', summary: 'Ask the provider about open checkouts', description: 'Records any that were paid (for when a webhook was missed).', - access: 'supervisor', campusScope: UNSCOPED, middleware: [cs.unscopedOnly], body: z.looseObject({}), v1: providers.checkCheckoutStatus, + access: 'supervisor', campusScope: UNSCOPED, middleware: [cs.unscopedOnly], body: z.looseObject({}), documented: { body: D.obj({ ids: D.ids.optional().describe('Checkouts to ask about (default: every open one), at most 200') }), response: D.obj({ results: z.array(D.anyObj), recorded: D.num.describe('Payments found and recorded'), message: D.str }) }, v1: providers.checkCheckoutStatus, }); v1Route({ - method: 'get', path: '/payments/stats', tag: 'Payments', summary: 'Payment totals', access: 'admin', query: paymentFilters, v1: pay.getPaymentStats, + method: 'get', path: '/payments/stats', tag: 'Payments', summary: 'Payment totals', access: 'admin', query: paymentFilters, documented: { response: D.obj({ totalToday: D.rand, totalWeek: D.rand, totalMonth: D.rand }) }, v1: pay.getPaymentStats, }); v1Route({ method: 'get', path: '/payments', tag: 'Payments', summary: 'Every payment', description: 'For the events you may see. `page` and `limit` page it (otherwise everything); see v1 for the filters it takes.', - access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: paymentFilters, v1: pay.getPayments, + access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: paymentFilters, documented: { response: D.v1Page(D.payment.extend({ registration: D.registration.nullish() })) }, v1: pay.getPayments, }); v1Route({ method: 'post', path: '/payments', tag: 'Payments', summary: 'Record a payment', @@ -72,129 +123,129 @@ v1Route({ access: 'supervisor', campusScope: 'scopeBody(registrationId, eventId; deny orphans)', status: 201, middleware: [cs.scopeBody([['registrationId', 'registration'], ['eventId', 'event']], { orphan: 'deny' })], body: z.looseObject({ registrationId: id.nullish(), eventId: id.nullish(), amount: z.union([z.number(), z.string()]), method: z.string().max(20).optional() }), - v1: pay.createPayment, + documented: { body: D.obj({ registrationId: D.optStr, eventId: D.optStr.describe('A donation: the event'), amount: D.numeric, method: D.str.describe('cash, card, eft or other'), isDonation: D.optBool, paidAt: D.optDate.describe('Backdate it'), userId: D.optStr.describe('A donation: who gave it') }), response: paymentFull }, v1: pay.createPayment, }); v1Route({ method: 'post', path: '/payments/refunds', tag: 'Payments', summary: 'Refund a payment', access: 'supervisor', campusScope: 'scopeBody(paymentId, registrationId; manage, deny orphans)', status: 201, middleware: [cs.scopeBody([['paymentId', 'payment'], ['registrationId', 'registration']], { need: 'manage', orphan: 'deny' })], - body: z.looseObject({ paymentId: id.optional(), registrationId: id.optional() }), v1: pay.createRefund, + body: z.looseObject({ paymentId: id.optional(), registrationId: id.optional() }), documented: { body: D.obj({ paymentId: D.optStr.describe('The payment refunded (or registrationId)'), registrationId: D.optStr, userId: D.str, amount: D.numeric.describe('Positive; stored as a negative payment'), method: D.str, reason: D.optStr }), response: D.payment }, v1: pay.createRefund, }); v1Route({ method: 'post', path: '/payments/donations/assign', tag: 'Payments', summary: 'Put a donation towards a registration', access: 'supervisor', campusScope: 'scopeBody(paymentId deny orphans; registrationId)', middleware: [cs.scopeBody([['paymentId', 'payment']], { orphan: 'deny' }), cs.scopeBody([['registrationId', 'registration']])], - body: z.looseObject({ paymentId: id, registrationId: id }), v1: pay.assignDonationToRegistration, + body: z.looseObject({ paymentId: id, registrationId: id }), documented: { body: D.obj({ paymentId: D.str.describe('The donation'), registrationId: D.str, amount: D.numeric.optional().describe('Default: as much as both allow') }), response: D.obj({ message: D.optStr, updatedRegistration: D.registration.optional(), generatedTickets: z.array(D.ticket).optional() }) }, v1: pay.assignDonationToRegistration, }); v1Route({ method: 'post', path: '/payments/donations/unassign', tag: 'Payments', summary: 'Take a donation back off a registration', access: 'supervisor', campusScope: 'scopeBody(legId; deny orphans)', middleware: [cs.scopeBody([['legId', 'payment']], { orphan: 'deny' })], - body: z.looseObject({ legId: id }), v1: pay.unassignDonationFromRegistration, + body: z.looseObject({ legId: id }), documented: { response: D.obj({ message: D.str, updatedRegistration: D.registration, donationId: D.str }) }, v1: pay.unassignDonationFromRegistration, }); v1Route({ method: 'post', path: '/donations/checkout', tag: 'Payments', summary: 'Give to an event', description: 'Starts a checkout for a donation of `amount` to `eventId`; answers where to send the person (`redirectUrl`).', - access: 'user', body: z.looseObject({ eventId: id, amount: z.union([z.number(), z.string()]) }), v1: pay.createCheckout, + access: 'user', body: z.looseObject({ eventId: id, amount: z.union([z.number(), z.string()]) }), documented: { body: D.obj({ eventId: D.str, amount: D.numeric, provider: D.optStr, successUrl: D.optStr, cancelUrl: D.optStr, failureUrl: D.optStr }), response: D.checkout.extend({ amount: D.rand, event: D.eventRef.partial() }) }, v1: pay.createCheckout, }); v1Route({ - method: 'get', path: '/me/payments', tag: 'Me', summary: 'My payments', access: 'user', query: paymentFilters, v1: pay.getUserPayments, + method: 'get', path: '/me/payments', tag: 'Me', summary: 'My payments', access: 'user', query: paymentFilters, documented: { response: D.v1Page(D.payment.extend({ registration: D.registration.nullish() })) }, v1: pay.getUserPayments, }); v1Route({ method: 'get', path: '/payments/:id', tag: 'Payments', summary: 'One payment', - access: 'user', campusScope: 'scopeEvent(payment, owner-ok)', middleware: [cs.scopeEvent({ resolve: 'payment', ownerOk: true })], params: idParams, v1: pay.getPaymentById, + access: 'user', campusScope: 'scopeEvent(payment, owner-ok)', middleware: [cs.scopeEvent({ resolve: 'payment', ownerOk: true })], params: idParams, documented: { response: D.payment.extend({ registration: D.registration.nullish() }) }, v1: pay.getPaymentById, }); v1Route({ method: 'post', path: '/payments/:id/receipt', tag: 'Payments', summary: 'Send the receipt again', access: 'user', campusScope: 'scopeEvent(payment, owner-ok)', middleware: [cs.scopeEvent({ resolve: 'payment', ownerOk: true })], params: idParams, - body: z.looseObject({ channel: z.string().max(20).optional() }), v1: pay.sendReceipt, + body: z.looseObject({ channel: z.string().max(20).optional() }), documented: { response: D.message }, v1: pay.sendReceipt, }); v1Route({ method: 'get', path: '/registrations/:id/payments', tag: 'Payments', summary: 'A registration\'s payments', access: 'user', campusScope: 'scopeEvent(registration, owner-ok)', middleware: [cs.scopeEvent({ resolve: 'registration', ownerOk: true })], params: idParams, - response: listData, map: ctx => ({ params: { registrationId: ctx.params.id } }), v1: pay.getPaymentsByRegistration, + response: listData, documented: { response: z.array(D.payment) }, map: ctx => ({ params: { registrationId: ctx.params.id } }), v1: pay.getPaymentsByRegistration, }); v1Route({ method: 'post', path: '/registrations/:id/payment-link', tag: 'Payments', summary: 'Make a link to pay', description: 'Supervisors: a checkout for `amount` (part of what\'s owed) for someone else to pay. Answers `redirectUrl` (the link) — or `priceUpdated` when an early-bird price ran out.', access: 'supervisor', campusScope: 'scopeEvent(registration)', middleware: [cs.scopeEvent({ resolve: 'registration' })], params: idParams, - body: z.looseObject({ amount: z.union([z.number(), z.string()]).optional() }), map: ctx => ({ body: { ...(ctx.req.body || {}), registrationId: ctx.params.id } }), v1: pay.createCheckout, + body: z.looseObject({ amount: z.union([z.number(), z.string()]).optional() }), map: ctx => ({ body: { ...(ctx.req.body || {}), registrationId: ctx.params.id } }), documented: { body: D.obj({ amount: D.numeric.optional(), donationAmount: D.numeric.optional(), provider: D.optStr, successUrl: D.optStr, cancelUrl: D.optStr, failureUrl: D.optStr }), response: D.checkout.extend({ priceUpdated: D.optBool, newTotal: D.optRand }) }, v1: pay.createCheckout, }); v1Route({ method: 'post', path: '/registrations/:id/payment-link/send', tag: 'Payments', summary: 'Send someone a link to pay', description: 'By email and/or WhatsApp, for what\'s still owing.', access: 'supervisor', campusScope: 'scopeEvent(registration)', middleware: [cs.scopeEvent({ resolve: 'registration' })], params: idParams, - body: z.looseObject({}), map: ctx => ({ body: { ...(ctx.req.body || {}), registrationId: ctx.params.id } }), v1: pay.sendPaymentLink, + body: z.looseObject({}), map: ctx => ({ body: { ...(ctx.req.body || {}), registrationId: ctx.params.id } }), documented: { body: D.obj({ redirectUrl: D.str.describe('The link to send'), channel: z.enum(['email', 'whatsapp']) }), response: D.obj({ sent: z.literal(true), channel: D.str }) }, v1: pay.sendPaymentLink, }); v1Route({ method: 'get', path: '/events/:id/payments', tag: 'Payments', summary: 'An event\'s payments', - access: 'staff', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, v1: pay.getPaymentsByEvent, + access: 'staff', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, documented: { response: z.array(D.payment) }, v1: pay.getPaymentsByEvent, }); v1Route({ method: 'get', path: '/payment-links/:id', tag: 'Payments', summary: 'A pay page', description: 'What a payment link shows: what\'s owed and the providers to pay with. The id in the link is the credential.', - access: 'public', params: idParams, v1: providers.getPayPage, + access: 'public', params: idParams, documented: { response: payPage }, v1: providers.getPayPage, }); v1Route({ method: 'post', path: '/payment-links/:id', tag: 'Payments', summary: 'Pay from a pay page', description: 'Starts a checkout with the chosen provider; answers where to send the person.', - access: 'public', params: idParams, body: z.looseObject({ provider: z.string().max(40).optional() }), v1: providers.choosePayProvider, + access: 'public', params: idParams, body: z.looseObject({ provider: z.string().max(40).optional() }), documented: { response: D.obj({ provider: D.str, redirectUrl: D.optStr, form: D.anyObj.nullish() }) }, v1: providers.choosePayProvider, }); // ─── Cash-ups ──────────────────────────────────────────────────────────────── const cashupBase = '/events/:id/cashup'; v1Route({ - method: 'get', path: '/cashups/audit', tag: 'Cash-ups', summary: 'Cash-up history', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventId', 'from', 'to'), v1: cashup.getCashupAudit, + method: 'get', path: '/cashups/audit', tag: 'Cash-ups', summary: 'Cash-up history', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventId', 'from', 'to'), documented: { response: z.array(cashupRecord) }, v1: cashup.getCashupAudit, }); v1Route({ method: 'get', path: cashupBase, tag: 'Cash-ups', summary: 'An event\'s cash-up', description: 'Income by method, costs, what each drawer should hold, and the saved draft.', - access: 'supervisor', campusScope: 'scopeEvent(manage)', middleware: [cs.scopeEvent({ need: 'manage' })], params: idParams, map: asEvent, v1: cashup.getEventCashup, + access: 'supervisor', campusScope: 'scopeEvent(manage)', middleware: [cs.scopeEvent({ need: 'manage' })], params: idParams, map: asEvent, documented: { response: D.obj({ event: D.anyObj, paymentsByMethod: D.anyObj.describe('Income per method'), totalRevenue: D.rand, costs: z.array(D.anyObj), totalCosts: D.rand, expectedCashByMethod: D.anyObj, reconciled: D.anyObj.nullish().describe('The last close, line by line'), netProfit: D.rand, totalDonations: D.rand, unallocatedDonationsTotal: D.rand, discountsTotal: D.optRand, salesByOption: z.array(D.anyObj).optional() }) }, v1: cashup.getEventCashup, }); v1Route({ method: 'get', path: `${cashupBase}/cash-by-user`, tag: 'Cash-ups', summary: 'Cash taken by each person', - access: 'supervisor', campusScope: 'scopeEvent(manage)', middleware: [cs.scopeEvent({ need: 'manage' })], params: idParams, map: asEvent, v1: cashup.getCashByRecordedUser, + access: 'supervisor', campusScope: 'scopeEvent(manage)', middleware: [cs.scopeEvent({ need: 'manage' })], params: idParams, map: asEvent, documented: { response: D.obj({ rows: z.array(D.anyObj).describe('Per person: who, cash recorded, cash counted'), cashActualTotal: D.optRand, cashDenominations: D.anyObj.nullish() }) }, v1: cashup.getCashByRecordedUser, }); v1Route({ method: 'put', path: `${cashupBase}/person-cash/:userId`, tag: 'Cash-ups', summary: 'Count one person\'s cash', access: 'supervisor', campusScope: 'scopeEvent(manage)', middleware: [cs.scopeEvent({ need: 'manage' })], params: z.object({ id, userId: id }), - body: z.looseObject({}), map: ctx => ({ params: { eventId: ctx.params.id, userId: ctx.params.userId } }), v1: cashup.savePersonCash, + body: z.looseObject({}), map: ctx => ({ params: { eventId: ctx.params.id, userId: ctx.params.userId } }), documented: { body: D.obj({ denominations: z.array(D.obj({ value: D.num.describe('The note or coin, in rand'), count: D.num })), notes: D.optStr }), response: D.anyObj.describe('The saved count') }, v1: cashup.savePersonCash, }); v1Route({ method: 'put', path: `${cashupBase}/draft`, tag: 'Cash-ups', summary: 'Save the cash-up as a draft', - access: 'admin', params: idParams, body: z.looseObject({}), map: asEvent, v1: cashup.saveEventCashupDraft, + access: 'admin', params: idParams, body: z.looseObject({}), map: asEvent, documented: { body: D.obj({ lines: z.array(cashupLineInput), notes: D.optStr }), response: D.message }, v1: cashup.saveEventCashupDraft, }); v1Route({ method: 'post', path: `${cashupBase}/close`, tag: 'Cash-ups', summary: 'Close the event', description: 'Admins. Nothing about the event\'s money can change until it\'s reopened.', - access: 'admin', params: idParams, body: z.looseObject({}), map: asEvent, v1: cashup.closeEvent, + access: 'admin', params: idParams, body: z.looseObject({}), map: asEvent, documented: { body: D.obj({ lines: z.array(cashupLineInput).optional().describe('Per payment method: in the bank, on hand, pending, write-offs (leave out for a quick close)'), notes: D.optStr }), response: cashupRecord }, v1: cashup.closeEvent, }); v1Route({ method: 'post', path: `${cashupBase}/reopen`, tag: 'Cash-ups', summary: 'Reopen a closed event', - access: 'admin', params: idParams, body: z.looseObject({}), map: asEvent, v1: cashup.reopenEvent, + access: 'admin', params: idParams, body: z.looseObject({}), map: asEvent, documented: { body: D.obj({ notes: D.optStr.describe('Why') }), response: cashupRecord }, v1: cashup.reopenEvent, }); v1Route({ method: 'post', path: '/cashup-lines/:id/pending', tag: 'Cash-ups', summary: 'Settle a pending cash-up line', - access: 'admin', params: idParams, body: z.looseObject({}), map: ctx => ({ params: { lineId: ctx.params.id } }), v1: cashup.resolvePending, + access: 'admin', params: idParams, body: z.looseObject({}), map: ctx => ({ params: { lineId: ctx.params.id } }), documented: { body: D.obj({ outcome: z.enum(['received', 'written_off']), amount: D.numeric, category: D.optStr.describe('A write-off: what it was for'), notes: D.optStr }), response: D.anyObj.describe('The settlement recorded') }, v1: cashup.resolvePending, }); // ─── Provider transactions ─────────────────────────────────────────────────── v1Route({ method: 'get', path: '/provider-transactions', tag: 'Payments', summary: 'Transactions from Yoco and PayFast', - access: 'supervisor', campusScope: UNSCOPED, middleware: [cs.unscopedOnly], query: filters('provider'), v1: ptx.getAllProviderTransactions, + access: 'supervisor', campusScope: UNSCOPED, middleware: [cs.unscopedOnly], query: filters('provider'), documented: { response: txAnswer(z.array(providerTransaction)) }, v1: ptx.getAllProviderTransactions, }); v1Route({ method: 'get', path: '/provider-transactions/unreconciled', tag: 'Payments', summary: 'Provider transactions not matched yet', - access: 'supervisor', campusScope: UNSCOPED, middleware: [cs.unscopedOnly], v1: ptx.getUnreconciledProviderTransactions, + access: 'supervisor', campusScope: UNSCOPED, middleware: [cs.unscopedOnly], documented: { response: txAnswer(z.array(providerTransaction)) }, v1: ptx.getUnreconciledProviderTransactions, }); v1Route({ method: 'post', path: '/provider-transactions/:id/reconcile', tag: 'Payments', summary: 'Match a provider transaction to a registration', - access: 'supervisor', campusScope: UNSCOPED, middleware: [cs.unscopedOnly], params: idParams, body: z.looseObject({}), v1: ptx.reconcileProviderTransaction, + access: 'supervisor', campusScope: UNSCOPED, middleware: [cs.unscopedOnly], params: idParams, body: z.looseObject({}), documented: { body: D.obj({ registrationId: D.optStr, eventId: D.optStr.describe('As a donation to this event instead'), userId: D.optStr }), response: txAnswer(D.obj({ transaction: providerTransaction, payment: D.payment, generatedTickets: z.array(D.ticket).optional() })) }, v1: ptx.reconcileProviderTransaction, }); v1Route({ method: 'post', path: '/provider-transactions/:id/ignore', tag: 'Payments', summary: 'Ignore a provider transaction', - access: 'supervisor', campusScope: UNSCOPED, middleware: [cs.unscopedOnly], params: idParams, body: z.looseObject({}), v1: ptx.ignoreProviderTransaction, + access: 'supervisor', campusScope: UNSCOPED, middleware: [cs.unscopedOnly], params: idParams, body: z.looseObject({}), documented: { response: txAnswer(providerTransaction) }, v1: ptx.ignoreProviderTransaction, }); // ─── Waitlist ──────────────────────────────────────────────────────────────── @@ -202,73 +253,78 @@ v1Route({ v1Route({ method: 'post', path: '/waitlist', tag: 'Waitlist', summary: 'Join a sold-out event\'s waitlist', description: 'Signed in, or with a name and email or phone. When places free up, people are offered them in order.', - access: 'optional', status: 201, body: z.looseObject({ eventId: id }), v1: waitlist.joinWaitlist, + access: 'optional', status: 201, body: z.looseObject({ eventId: id }), documented: { body: D.obj({ eventId: D.str, eventOptionId: D.str, variantId: D.optStr, sessionId: D.optStr.describe('Per-session tickets: the session'), quantity: D.numeric, guestName: D.optStr.describe('Not signed in'), guestEmail: D.optStr, guestPhone: D.optStr }), response: waitlistEntry.extend({ ahead: D.num.describe('People ahead'), message: D.str }) }, v1: waitlist.joinWaitlist, }); -v1Route({ method: 'get', path: '/me/waitlist', tag: 'Me', summary: 'Waitlists I\'m on', access: 'user', v1: waitlist.myWaitlist }); +v1Route({ method: 'get', path: '/me/waitlist', tag: 'Me', summary: 'Waitlists I\'m on', access: 'user', documented: { response: z.array(waitlistEntry) }, v1: waitlist.myWaitlist }); v1Route({ method: 'get', path: '/waitlist/claims/:token', tag: 'Waitlist', summary: 'A waitlist offer', description: 'What an offer link shows (the token is the credential). Register with `waitlistToken` to take it.', - access: 'public', middleware: [linkLimiter()], params: tokenParams, v1: waitlist.claimInfo, + access: 'public', middleware: [linkLimiter()], params: tokenParams, documented: { response: D.obj({ eventId: D.optStr, eventTitle: D.optStr, eventStart: D.optDate, eventOptionId: D.str, optionName: D.str, variantId: D.optStr, variantName: D.optStr, sessionId: D.optStr, sessionName: D.optStr, sessionStart: D.optDate, lineName: D.str, quantity: D.optNum.describe('Places offered'), requested: D.num, expiresAt: D.optDate, name: D.optStr }) }, v1: waitlist.claimInfo, }); v1Route({ method: 'get', path: '/events/:id/waitlist', tag: 'Waitlist', summary: 'An event\'s waitlist', - access: 'staff', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, query: filters('all'), map: asEvent, v1: waitlist.eventWaitlist, + access: 'staff', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, query: filters('all'), map: asEvent, documented: { response: z.array(waitlistEntry.extend({ user: D.userSummary.nullish() })) }, v1: waitlist.eventWaitlist, }); for (const [action, summary, handler] of [['offer', 'Offer someone their places now', waitlist.offerManually], ['move', 'Move someone up or down the waitlist', waitlist.moveEntry], ['remove', 'Take someone off the waitlist', waitlist.removeEntry]] as const) { v1Route({ method: 'post', path: `/waitlist/:id/${action}`, tag: 'Waitlist', summary, access: 'supervisor', campusScope: 'scopeEvent(waitlistEntry)', middleware: [cs.scopeEvent({ resolve: 'waitlistEntry' })], params: idParams, body: z.looseObject({}), v1: handler, + documented: { + body: action === 'offer' ? D.obj({ quantity: D.numeric.optional().describe('Places to offer (default: all they asked for)') }) + : action === 'move' ? D.obj({ direction: z.enum(['up', 'down']) }) : D.anyObj, + response: D.message, + }, }); } -v1Route({ method: 'delete', path: '/waitlist/:id', tag: 'Waitlist', summary: 'Leave a waitlist', access: 'user', params: idParams, v1: waitlist.leaveWaitlist }); +v1Route({ method: 'delete', path: '/waitlist/:id', tag: 'Waitlist', summary: 'Leave a waitlist', access: 'user', params: idParams, documented: { response: D.message }, v1: waitlist.leaveWaitlist }); // ─── Sponsorship ───────────────────────────────────────────────────────────── v1Route({ method: 'get', path: '/events/:id/sponsorship', tag: 'Sponsorship', summary: 'Sponsoring places at an event', - description: 'Whether it\'s on, and the suggested amounts.', access: 'public', params: idParams, map: asEvent, v1: sponsor.getEventSponsorship, + description: 'Whether it\'s on, and the suggested amounts.', access: 'public', params: idParams, map: asEvent, documented: { response: D.obj({ enabled: D.bool, open: D.optBool, spotPrice: D.optRand, showProgress: D.optBool, goalSpots: D.optNum, spotsFunded: D.optNum, sponsors: z.unknown().optional() }) }, v1: sponsor.getEventSponsorship, }); v1Route({ method: 'get', path: '/events/:id/sponsorship/pool', tag: 'Sponsorship', summary: 'The sponsorship pool', - description: 'What\'s been given and what\'s been used.', access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, v1: sponsor.getPool, + description: 'What\'s been given and what\'s been used.', access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, documented: { response: D.obj({ eventId: D.str, spotPrice: D.rand, goalSpots: D.optNum }).describe('Plus the pool: given, used and places funded') }, v1: sponsor.getPool, }); v1Route({ method: 'post', path: '/sponsorships/checkout', tag: 'Sponsorship', summary: 'Give towards places', - description: 'Starts a checkout; answers where to send the person.', access: 'optional', body: z.looseObject({ eventId: id }), v1: sponsor.createSponsorCheckout, + description: 'Starts a checkout; answers where to send the person.', access: 'optional', body: z.looseObject({ eventId: id }), documented: { body: D.obj({ eventId: D.str, spots: D.numeric.optional().describe('Places to fund (or amount)'), amount: D.numeric.optional(), anonymous: D.optBool, sponsorName: D.optStr, message: D.optStr, name: D.optStr.describe('Not signed in'), email: D.optStr, phone: D.optStr, provider: D.optStr }), response: D.checkout.extend({ amount: D.rand }) }, v1: sponsor.createSponsorCheckout, }); // ─── Consent ───────────────────────────────────────────────────────────────── v1Route({ method: 'get', path: '/events/:id/consent', tag: 'Consent', summary: 'Parental consent for an event', - access: 'staff', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, v1: consent.listEventConsent, + access: 'staff', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, documented: { response: D.obj({ event: D.anyObj, counts: z.record(z.string(), z.number()).describe('Status → how many'), rows: z.array(consentRow) }) }, v1: consent.listEventConsent, }); v1Route({ method: 'get', path: '/events/:id/consent/medical', tag: 'Consent', summary: 'Medical notes from consent forms', - access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, v1: consent.medicalList, + access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, documented: { response: D.obj({ event: D.eventRef.partial(), rows: z.array(D.obj({ name: D.str, dateOfBirth: D.optDate, parentName: D.optStr, parentPhone: D.optStr, parentEmail: D.optStr, medical: D.anyObj.nullish(), emergency: D.anyObj.nullish(), photoConsent: D.optBool, purged: D.bool.describe('Medical details removed after the event') })) }) }, v1: consent.medicalList, }); v1Route({ method: 'post', path: '/events/:id/consent/resend-pending', tag: 'Consent', summary: 'Remind everyone who hasn\'t answered', - access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, body: z.looseObject({}), map: asEvent, v1: consent.resendPending, + access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, body: z.looseObject({}), map: asEvent, documented: { response: D.obj({ message: D.str, sent: D.num, pending: D.num }) }, v1: consent.resendPending, }); v1Route({ method: 'post', path: '/events/:id/consent/rerequest', tag: 'Consent', summary: 'Ask for consent again', description: 'After the consent wording changed.', access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, - body: z.looseObject({}), map: ctx => ({ params: { eventId: ctx.params.id }, body: ctx.req.body }), v1: consent.rerequestConsent, + body: z.looseObject({}), map: ctx => ({ params: { eventId: ctx.params.id }, body: ctx.req.body }), documented: { response: D.obj({ message: D.str, created: D.num }) }, v1: consent.rerequestConsent, }); v1Route({ method: 'post', path: '/consent-requests/:id/resend', tag: 'Consent', summary: 'Send a consent request again', access: 'user', campusScope: 'scopeEvent(consentRequest, owner-ok)', middleware: [cs.scopeEvent({ resolve: 'consentRequest', ownerOk: true })], params: idParams, - body: z.looseObject({}), v1: consent.resendRequest, + body: z.looseObject({}), documented: { response: D.message }, v1: consent.resendRequest, }); v1Route({ method: 'get', path: '/consent/:token', tag: 'Consent', summary: 'A consent form', description: 'What the link in a consent request shows (the token is the parent\'s credential).', - access: 'public', middleware: [linkLimiter()], params: tokenParams, v1: consent.getConsent, + access: 'public', middleware: [linkLimiter()], params: tokenParams, documented: { response: D.obj({ status: D.str, superseded: D.bool, expired: D.bool, respondedAt: D.optDate, attendeeName: D.str, parentName: D.optStr, consentText: D.str, textVersion: D.optNum, event: D.obj({ title: D.str, startDate: D.date, endDate: D.date, location: D.optStr }), collect: D.obj({ medical: D.bool, emergency: D.bool, photo: D.bool }).describe('What the form asks for') }) }, v1: consent.getConsent, }); v1Route({ method: 'post', path: '/consent/:token', tag: 'Consent', summary: 'Answer a consent form', - access: 'public', middleware: [linkLimiter()], params: tokenParams, body: z.looseObject({}), v1: consent.answerConsent, + access: 'public', middleware: [linkLimiter()], params: tokenParams, body: z.looseObject({}), documented: { body: D.obj({ decision: z.enum(['give', 'decline']), signedName: D.str, isGuardian: D.bool.describe('Must be true'), medical: D.obj({ allergies: D.optStr, medication: D.optStr, conditions: D.optStr, medicalAid: D.optStr }).optional(), emergency: D.obj({ name: D.str, phone: D.str, relationship: D.optStr }).optional(), photoConsent: D.optBool }), response: D.obj({ message: D.str, status: z.enum(['given', 'declined']) }) }, v1: consent.answerConsent, }); // ─── Attendee form answers ─────────────────────────────────────────────────── @@ -276,35 +332,35 @@ v1Route({ v1Route({ method: 'get', path: '/form-responses', tag: 'Registrations', summary: 'Attendee form answers', description: 'For an event (`eventId`) or a registration (`registrationId`), for events you may see.', - access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventId', 'registrationId', 'userId', 'cursor'), v1: forms.listFormResponses, + access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventId', 'registrationId', 'userId', 'cursor'), documented: { response: D.obj({ items: z.array(D.obj({ id: D.str, registrationId: D.str, attendeeId: D.optStr, createdAt: D.date, answers: z.array(D.obj({ fieldId: D.str, value: D.str })).optional() })), nextCursor: D.optStr.describe('Pass as `cursor` for the next page') }) }, v1: forms.listFormResponses, }); // ─── Feedback ──────────────────────────────────────────────────────────────── v1Route({ - method: 'get', path: '/feedback/summary', tag: 'Feedback', summary: 'Feedback across events', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventIds'), v1: feedback.getSummary, + method: 'get', path: '/feedback/summary', tag: 'Feedback', summary: 'Feedback across events', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventIds'), documented: { response: z.array(D.obj({ eventId: D.str, title: D.str, startDate: D.date, anonymous: D.bool, sentAt: D.optDate, invited: D.num, responses: D.num, responseRate: D.optNum.describe('%'), questions: z.array(D.anyObj).describe('Each question with its answers summarised') })) }, v1: feedback.getSummary, }); v1Route({ method: 'get', path: '/feedback-forms/:token', tag: 'Feedback', summary: 'A feedback form', - description: 'What the link sent after an event shows (the token is the credential).', access: 'public', params: tokenParams, v1: feedback.getPublicForm, + description: 'What the link sent after an event shows (the token is the credential).', access: 'public', params: tokenParams, documented: { response: D.obj({ event: D.anyObj, name: D.str, intro: D.optStr, anonymous: D.bool, responded: D.bool, fields: z.array(feedbackField) }) }, v1: feedback.getPublicForm, }); v1Route({ method: 'post', path: '/feedback-forms/:token', tag: 'Feedback', summary: 'Answer a feedback form', - access: 'public', params: tokenParams, body: z.looseObject({}), v1: feedback.submitPublicForm, + access: 'public', params: tokenParams, body: z.looseObject({}), documented: { body: D.obj({ answers: z.record(z.string(), z.unknown()).describe('Field id → answer') }), response: D.message }, v1: feedback.submitPublicForm, }); v1Route({ method: 'get', path: '/events/:id/feedback', tag: 'Feedback', summary: 'An event\'s feedback set-up and answers', - access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, v1: feedback.getEventFeedback, + access: 'supervisor', campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()], params: idParams, map: asEvent, documented: { response: feedbackForm }, v1: feedback.getEventFeedback, }); v1Route({ method: 'put', path: '/events/:id/feedback', tag: 'Feedback', summary: 'Set up an event\'s feedback form', - access: 'supervisor', campusScope: 'scopeEvent(manage)', middleware: [cs.scopeEvent({ need: 'manage' })], params: idParams, body: z.looseObject({}), map: asEvent, v1: feedback.saveEventFeedback, + access: 'supervisor', campusScope: 'scopeEvent(manage)', middleware: [cs.scopeEvent({ need: 'manage' })], params: idParams, body: z.looseObject({}), map: asEvent, documented: { body: D.obj({ sendAt: D.optDate, audience: D.optStr.describe('checked_in or everyone'), anonymous: D.optBool, intro: D.optStr, fields: z.array(feedbackField) }), response: feedbackForm }, v1: feedback.saveEventFeedback, }); v1Route({ method: 'delete', path: '/events/:id/feedback', tag: 'Feedback', summary: 'Remove an event\'s feedback form', - access: 'supervisor', campusScope: 'scopeEvent(manage)', middleware: [cs.scopeEvent({ need: 'manage' })], params: idParams, map: asEvent, v1: feedback.deleteEventFeedback, + access: 'supervisor', campusScope: 'scopeEvent(manage)', middleware: [cs.scopeEvent({ need: 'manage' })], params: idParams, map: asEvent, documented: { response: D.message }, v1: feedback.deleteEventFeedback, }); v1Route({ method: 'post', path: '/events/:id/feedback/send-now', tag: 'Feedback', summary: 'Send the feedback form now', - access: 'supervisor', campusScope: 'scopeEvent(manage)', middleware: [cs.scopeEvent({ need: 'manage' })], params: idParams, body: z.looseObject({}), map: asEvent, v1: feedback.sendNow, + access: 'supervisor', campusScope: 'scopeEvent(manage)', middleware: [cs.scopeEvent({ need: 'manage' })], params: idParams, body: z.looseObject({}), map: asEvent, documented: { response: D.obj({ invited: D.num, message: D.str }) }, v1: feedback.sendNow, }); diff --git a/apps/events/backend/src/v2/resources/peopleMessaging.ts b/apps/events/backend/src/v2/resources/peopleMessaging.ts index 9b885c9..732618f 100644 --- a/apps/events/backend/src/v2/resources/peopleMessaging.ts +++ b/apps/events/backend/src/v2/resources/peopleMessaging.ts @@ -9,6 +9,7 @@ import { z } from 'zod'; import type { Request } from 'express'; import { id, idParams } from '../schemas'; import { v1Route } from '../viaV1'; +import * as D from '../docs'; /* eslint-disable @typescript-eslint/no-explicit-any -- v1 handlers and middleware are JavaScript */ const rateLimit = require('express-rate-limit') as (opts: object) => any; @@ -38,38 +39,76 @@ const dashboardRouter = require('../../routes/dashboardRoutes'); const loose = z.looseObject({}); const filters = (...names: string[]) => z.looseObject(Object.fromEntries(names.map(n => [n, z.string().max(4000).optional()]))); const SCOPE_LIST = 'scopeList (the handler filters by listWhere)'; + +// ─── Documented shapes (docs.ts) ───────────────────────────────────────────── + +const challenge = D.obj({ challengeId: D.str, method: z.enum(['email', 'whatsapp']), destination: D.str.describe('Where the code went, partly hidden') }); +const signedIn = D.obj({ message: D.optStr, id: D.str, name: D.str, email: D.str, role: D.str, token: D.str.describe('A new sign-in token') }); +const kind = z.enum(['update', 'news']).describe('update: about something they booked (always sent). news: needs their news consent'); +const attendeeFilter = D.obj({ + status: D.optStr.describe('any, paid, unpaid, checked_in, not_checked_in…'), attendeeIds: D.ids.optional(), registrationIds: D.ids.optional(), + allocationGroupId: D.optStr.describe('People in one room or group'), name: D.optStr, email: D.optStr, phone: D.optStr, + audience: z.enum(['sponsors']).optional().describe('Sponsors of the event instead'), +}); +const emailAttendees = D.obj({ + subject: D.optStr, html: D.optStr, text: D.optStr.describe('subject and html or text, unless template is tickets'), + template: z.enum(['custom', 'tickets', 'payment_reminder', 'event_reminder']).optional().describe('tickets: send everyone their tickets; the reminders fill in a standard message'), filter: attendeeFilter.optional(), + dryRun: D.optBool.describe('Only say who it would reach'), kind: kind.optional(), promoEventId: D.optStr.describe('Promote another event (news)'), +}); +const whatsappAttendees = D.obj({ + message: D.optStr.describe('Required unless template is tickets'), template: z.enum(['custom', 'tickets', 'payment_reminder', 'event_reminder']).optional(), filter: attendeeFilter.optional(), + dryRun: D.optBool, kind: kind.optional(), promoEventId: D.optStr, +}); +const reach = D.obj({ eventId: D.optStr, kind: D.optStr, matched: D.num, skipped: D.optNum.describe('Left out: no news consent'), recipients: z.array(D.anyObj).optional().describe('The first 20'), queued: D.optNum, template: D.optStr, sent: D.optNum }); +const scheduledJob = D.obj({ + id: D.str, kind: D.str.describe('broadcast or attendees'), eventId: D.optStr, broadcast: D.bool, channel: z.enum(['email', 'whatsapp']).or(D.str), + recipient: D.optStr, scheduledAt: D.date, createdAt: D.date, status: D.str.describe('queued, sent, failed, cancelled'), attempts: D.num, + sentAt: D.optDate, lastError: D.optStr, subject: D.str, html: D.str, text: D.str, message: D.str, hasHtml: D.bool, hasText: D.bool, +}); +const scheduled = D.obj({ message: D.str, job: D.anyObj }); +const bannerShape = D.obj({ message: D.str, type: D.str.describe('info, warning, success, error'), liveFrom: D.optDate, liveTill: D.optDate }); +const savedFilter = D.obj({ id: D.str, page: D.str.describe('The list page it belongs to'), name: D.str, params: D.anyObj.describe('The filters'), isDefault: D.bool, updatedAt: D.date }); +const scanStats = D.obj({ totalToday: D.num, myToday: D.num, lastHour: D.num, byStaff: z.array(D.anyObj) }).partial(); +const monthly = D.obj({ thisMonth: D.num, lastMonth: D.num, pctChange: D.optNum }); +const reportBody = D.obj({ + title: D.str, subtitle: D.optStr, kind: z.enum(['table', 'layered']), + table: D.obj({ columns: z.array(D.str), rows: z.array(z.array(z.unknown())) }).optional().describe('kind table'), + layered: D.obj({ header: D.optStr, sections: z.array(D.anyObj) }).optional().describe('kind layered: titled sections, each with its rows'), + orientation: z.enum(['portrait', 'landscape']).optional(), stats: z.array(D.anyObj).optional().describe('Figures shown above the table'), + chart: D.anyObj.optional(), note: D.optStr, extraTables: z.array(D.anyObj).optional(), +}); /** The query string of the v2 request, for a v1 router's URL. */ const qs = (req: Request) => (req.originalUrl.includes('?') ? req.originalUrl.slice(req.originalUrl.indexOf('?')) : ''); // ─── Accounts ──────────────────────────────────────────────────────────────── -v1Route({ method: 'post', path: '/auth/login/code/resend', tag: 'Accounts', summary: 'Send the sign-in code again', access: 'public', middleware: [loginLimiter], body: loose, v1: users.resendLoginTwoFactor }); -v1Route({ method: 'post', path: '/auth/password/forgot', tag: 'Accounts', summary: 'Email me a link to reset my password', description: 'Always the same answer, so it doesn\'t say whether an account has that email. Rate-limited like sign-in.', access: 'public', middleware: [loginLimiter], body: z.looseObject({ email: z.string().max(200) }), v1: users.requestPasswordReset }); -v1Route({ method: 'post', path: '/auth/password/reset', tag: 'Accounts', summary: 'Set a new password with a reset link', access: 'public', body: loose, v1: users.resetPassword }); -v1Route({ method: 'post', path: '/auth/activate', tag: 'Accounts', summary: 'Activate an account with its link', access: 'public', body: loose, v1: users.activateAccount }); -v1Route({ method: 'post', path: '/me/sessions/revoke', tag: 'Me', summary: 'Sign out everywhere else', access: 'user', body: loose, v1: users.revokeMySession }); -v1Route({ method: 'post', path: '/me/close', tag: 'Me', summary: 'Close my account', description: 'Needs the password. Personal details are removed; payment records stay, anonymised.', access: 'user', body: loose, v1: users.closeAccount }); -v1Route({ method: 'get', path: '/me/activity', tag: 'Me', summary: 'Recent sign-ins and changes to my account', access: 'user', v1: users.getMyActivity }); -v1Route({ method: 'post', path: '/me/verify-password', tag: 'Me', summary: 'Check my password (before a sensitive change)', access: 'user', middleware: [loginLimiter], body: loose, v1: users.verifyPassword }); -v1Route({ method: 'post', path: '/me/two-factor/enable', tag: 'Me', summary: 'Start turning on two-step sign-in', description: 'Sends a code to confirm with.', access: 'user', middleware: [loginLimiter], body: loose, v1: users.startEnableTwoFactor }); -v1Route({ method: 'post', path: '/me/two-factor/confirm', tag: 'Me', summary: 'Confirm two-step sign-in with the code', access: 'user', middleware: [loginLimiter], body: loose, v1: users.confirmEnableTwoFactor }); -v1Route({ method: 'post', path: '/me/two-factor/disable', tag: 'Me', summary: 'Turn off two-step sign-in', access: 'user', middleware: [loginLimiter], body: loose, v1: users.disableTwoFactor }); +v1Route({ method: 'post', path: '/auth/login/code/resend', tag: 'Accounts', summary: 'Send the sign-in code again', access: 'public', middleware: [loginLimiter], body: loose, documented: { body: D.obj({ challengeId: D.str }), response: challenge }, v1: users.resendLoginTwoFactor }); +v1Route({ method: 'post', path: '/auth/password/forgot', tag: 'Accounts', summary: 'Email me a link to reset my password', description: 'Always the same answer, so it doesn\'t say whether an account has that email. Rate-limited like sign-in.', access: 'public', middleware: [loginLimiter], body: z.looseObject({ email: z.string().max(200) }), documented: { response: D.message }, v1: users.requestPasswordReset }); +v1Route({ method: 'post', path: '/auth/password/reset', tag: 'Accounts', summary: 'Set a new password with a reset link', access: 'public', body: loose, documented: { body: D.obj({ token: D.str.describe('From the link'), password: D.str }), response: D.message }, v1: users.resetPassword }); +v1Route({ method: 'post', path: '/auth/activate', tag: 'Accounts', summary: 'Activate an account with its link', access: 'public', body: loose, documented: { body: D.obj({ token: D.str.describe('From the link'), password: D.str.describe('At least 8 characters'), acceptTerms: D.optBool }), response: signedIn }, v1: users.activateAccount }); +v1Route({ method: 'post', path: '/me/sessions/revoke', tag: 'Me', summary: 'Sign out everywhere else', access: 'user', body: loose, documented: { response: D.obj({ message: D.str, token: D.str.describe('A new token for this device (the old one stops working)') }) }, v1: users.revokeMySession }); +v1Route({ method: 'post', path: '/me/close', tag: 'Me', summary: 'Close my account', description: 'Needs the password. Personal details are removed; payment records stay, anonymised.', access: 'user', body: loose, documented: { body: D.obj({ password: D.str, deleteData: D.optBool.describe('Also ask for my personal information to be deleted') }), response: D.message }, v1: users.closeAccount }); +v1Route({ method: 'get', path: '/me/activity', tag: 'Me', summary: 'Recent sign-ins and changes to my account', access: 'user', documented: { response: z.array(D.obj({ id: D.str, type: D.str.describe('login, password_changed, two_factor_enabled…'), device: D.optStr, createdAt: D.date })) }, v1: users.getMyActivity }); +v1Route({ method: 'post', path: '/me/verify-password', tag: 'Me', summary: 'Check my password (before a sensitive change)', access: 'user', middleware: [loginLimiter], body: loose, documented: { body: D.obj({ password: D.str }), response: D.ok }, v1: users.verifyPassword }); +v1Route({ method: 'post', path: '/me/two-factor/enable', tag: 'Me', summary: 'Start turning on two-step sign-in', description: 'Sends a code to confirm with.', access: 'user', middleware: [loginLimiter], body: loose, documented: { body: D.obj({ method: z.enum(['email', 'whatsapp']), password: D.str }), response: challenge }, v1: users.startEnableTwoFactor }); +v1Route({ method: 'post', path: '/me/two-factor/confirm', tag: 'Me', summary: 'Confirm two-step sign-in with the code', access: 'user', middleware: [loginLimiter], body: loose, documented: { body: D.obj({ challengeId: D.str, code: D.str }), response: D.obj({ twoFactorEnabled: z.literal(true), twoFactorMethod: D.str }) }, v1: users.confirmEnableTwoFactor }); +v1Route({ method: 'post', path: '/me/two-factor/disable', tag: 'Me', summary: 'Turn off two-step sign-in', access: 'user', middleware: [loginLimiter], body: loose, documented: { body: D.obj({ password: D.str }), response: D.obj({ twoFactorEnabled: z.literal(false), twoFactorMethod: z.null() }) }, v1: users.disableTwoFactor }); v1Route({ method: 'get', path: '/users/exists', tag: 'Accounts', summary: 'Is there an account with this email or phone?', access: 'supervisor', campusScope: 'campusIndependent (accounts are shared across campuses)', middleware: [cs.campusIndependent('accounts are shared across campuses')], - query: filters('email', 'phone', 'phoneNumber'), v1: users.checkUserExists, + query: filters('email', 'phone', 'phoneNumber'), documented: { response: D.obj({ exists: D.bool, hasEmail: D.optBool, hasPhone: D.optBool, user: D.obj({ id: D.str, name: D.str, email: D.optStr, phoneNumber: D.optStr, notificationPreference: D.optStr }).nullish() }) }, v1: users.checkUserExists, }); v1Route({ method: 'get', path: '/users', tag: 'Accounts', summary: 'Every account', description: 'Paged (`page`, `limit`) and searchable (`q`, `role`, `campus`, …) — see v1 for every filter.', access: 'supervisor', campusScope: 'campusIndependent (accounts are shared across campuses)', middleware: [cs.campusIndependent('accounts are shared across campuses')], - query: filters('page', 'limit', 'search', 'role', 'isActive', 'campus'), v1: users.getUsers, + query: filters('page', 'limit', 'search', 'role', 'isActive', 'campus'), documented: { response: D.v1Page(D.user) }, v1: users.getUsers, }); -v1Route({ method: 'get', path: '/users/:id', tag: 'Accounts', summary: 'One account', access: 'admin', params: idParams, v1: users.getUserById }); -v1Route({ method: 'patch', path: '/users/:id', tag: 'Accounts', summary: 'Change an account', description: 'Name, contact details, role, campus limits, active.', access: 'admin', params: idParams, body: loose, v1: users.updateUser }); -v1Route({ method: 'delete', path: '/users/:id', tag: 'Accounts', summary: 'Delete an account', access: 'admin', params: idParams, v1: users.deleteUser }); -v1Route({ method: 'post', path: '/users/:id/sessions/revoke', tag: 'Accounts', summary: 'Sign someone out everywhere', access: 'admin', params: idParams, body: loose, v1: users.adminRevokeUserSessions }); -v1Route({ method: 'post', path: '/users/:id/anonymize', tag: 'Accounts', summary: 'Anonymise an account', description: 'Admins. Personal details are removed for good; payment records stay.', access: 'admin', params: idParams, body: loose, v1: users.anonymizeUser }); +v1Route({ method: 'get', path: '/users/:id', tag: 'Accounts', summary: 'One account', access: 'admin', params: idParams, documented: { response: D.user.extend({ scopedCampusIds: D.ids.optional().describe('Campuses they\'re limited to') }) }, v1: users.getUserById }); +v1Route({ method: 'patch', path: '/users/:id', tag: 'Accounts', summary: 'Change an account', description: 'Name, contact details, role, campus limits, active.', access: 'admin', params: idParams, body: loose, documented: { body: D.obj({ name: D.optStr, email: D.optStr, phoneNumber: D.optStr, role: D.optStr.describe('admin, supervisor, staff or user'), isActive: D.optBool, password: D.optStr.describe('Set a new password'), notificationPreference: D.optStr.describe('email, whatsapp or both'), twoFactorEnabled: D.optBool.describe('Only to turn it off'), scopedCampusIds: D.ids.optional().describe('Limit staff to these campuses (empty: all)') }), response: D.user }, v1: users.updateUser }); +v1Route({ method: 'delete', path: '/users/:id', tag: 'Accounts', summary: 'Delete an account', access: 'admin', params: idParams, documented: { response: D.message }, v1: users.deleteUser }); +v1Route({ method: 'post', path: '/users/:id/sessions/revoke', tag: 'Accounts', summary: 'Sign someone out everywhere', access: 'admin', params: idParams, body: loose, documented: { response: D.message }, v1: users.adminRevokeUserSessions }); +v1Route({ method: 'post', path: '/users/:id/anonymize', tag: 'Accounts', summary: 'Anonymise an account', description: 'Admins. Personal details are removed for good; payment records stay.', access: 'admin', params: idParams, body: loose, documented: { response: D.message }, v1: users.anonymizeUser }); // ─── Messaging an event's people ───────────────────────────────────────────── @@ -77,62 +116,72 @@ const toEvent = { campusScope: 'scopeEvent(view)', middleware: [cs.scopeEvent()] v1Route({ method: 'get', path: '/event-listing', tag: 'Events', summary: 'Upcoming public events in full', description: 'What the site\'s event lists show (ticket options, prices, early-bird tiers), not paged. `campus` (id or slug) and `series` (slug) narrow it. For a paged, slimmer list use GET /events.', - access: 'public', query: filters('campus', 'series'), v1: events.getEvents, + access: 'public', query: filters('campus', 'series'), documented: { response: z.array(D.event.extend({ eventOptions: z.array(D.eventOption).optional(), isSoldOut: D.optBool })) }, v1: events.getEvents, }); -v1Route({ method: 'get', path: '/admin/events', tag: 'Events (staff)', summary: 'Every event, including deactivated ones', access: 'admin', v1: events.getAllEvents }); -v1Route({ method: 'post', path: '/events/:id/email-attendees', tag: 'Messaging', summary: 'Email an event\'s people', description: 'Filtered by status or chosen people; news consent is checked.', access: 'supervisor', ...toEvent, params: idParams, body: loose, v1: events.emailEventAttendees }); -v1Route({ method: 'post', path: '/events/:id/email-attendees/schedule', tag: 'Messaging', summary: 'Schedule an email to an event\'s people', access: 'supervisor', ...toEvent, params: idParams, body: loose, v1: events.scheduleEmailEventAttendees }); -v1Route({ method: 'post', path: '/events/:id/whatsapp-attendees', tag: 'Messaging', summary: 'WhatsApp an event\'s people', access: 'supervisor', ...toEvent, params: idParams, body: loose, v1: events.whatsappEventAttendees }); -v1Route({ method: 'post', path: '/events/:id/whatsapp-attendees/schedule', tag: 'Messaging', summary: 'Schedule a WhatsApp to an event\'s people', access: 'supervisor', ...toEvent, params: idParams, body: loose, v1: events.scheduleWhatsappEventAttendees }); +v1Route({ method: 'get', path: '/admin/events', tag: 'Events (staff)', summary: 'Every event, including deactivated ones', access: 'admin', documented: { response: z.array(D.event) }, v1: events.getAllEvents }); +v1Route({ method: 'post', path: '/events/:id/email-attendees', tag: 'Messaging', summary: 'Email an event\'s people', description: 'Filtered by status or chosen people; news consent is checked.', access: 'supervisor', ...toEvent, params: idParams, body: loose, documented: { body: emailAttendees, response: reach }, v1: events.emailEventAttendees }); +v1Route({ method: 'post', path: '/events/:id/email-attendees/schedule', tag: 'Messaging', summary: 'Schedule an email to an event\'s people', access: 'supervisor', ...toEvent, params: idParams, body: loose, documented: { body: emailAttendees.extend({ scheduledAt: D.date }), response: scheduled }, v1: events.scheduleEmailEventAttendees }); +v1Route({ method: 'post', path: '/events/:id/whatsapp-attendees', tag: 'Messaging', summary: 'WhatsApp an event\'s people', access: 'supervisor', ...toEvent, params: idParams, body: loose, documented: { body: whatsappAttendees, response: reach }, v1: events.whatsappEventAttendees }); +v1Route({ method: 'post', path: '/events/:id/whatsapp-attendees/schedule', tag: 'Messaging', summary: 'Schedule a WhatsApp to an event\'s people', access: 'supervisor', ...toEvent, params: idParams, body: loose, documented: { body: whatsappAttendees.extend({ scheduledAt: D.date }), response: scheduled }, v1: events.scheduleWhatsappEventAttendees }); for (const [channel, field, ctrl] of [['email', 'emails', bc], ['whatsapp', 'phones', wbc]] as const) { const scope = { campusScope: `scopeBroadcast(freeform ${field})`, middleware: [cs.scopeBroadcast({ freeformField: field })] }; const [preview, send, schedule] = channel === 'email' ? [ctrl.previewBroadcast, ctrl.sendBroadcast, ctrl.scheduleBroadcast] : [ctrl.previewWhatsAppBroadcast, ctrl.sendWhatsAppBroadcast, ctrl.scheduleWhatsAppBroadcast]; const name = channel === 'email' ? 'an email' : 'a WhatsApp'; - v1Route({ method: 'post', path: `/broadcasts/${channel}/preview`, tag: 'Messaging', summary: `Who ${name} broadcast would reach`, access: 'supervisor', ...scope, body: loose, v1: preview }); - v1Route({ method: 'post', path: `/broadcasts/${channel}/send`, tag: 'Messaging', summary: `Send ${name} broadcast`, description: 'To campuses, events, roles or listed people; news consent is checked.', access: 'supervisor', ...scope, body: loose, v1: send }); - v1Route({ method: 'post', path: `/broadcasts/${channel}/schedule`, tag: 'Messaging', summary: `Schedule ${name} broadcast`, access: 'supervisor', ...scope, body: loose, v1: schedule }); + const who = D.obj({ + userIds: D.ids.optional().describe('Chosen accounts'), + ...(channel === 'email' ? { emails: D.optStr.describe('Typed-in addresses, separated by commas or new lines') } : { phones: D.optStr.describe('Typed-in numbers, separated by commas or new lines') }), + eventId: D.optStr.describe('Everyone registered for this event'), kind: kind.optional().describe('Default news'), + }); + const content = channel === 'email' ? { subject: D.str, html: D.optStr, text: D.optStr } : { message: D.str }; + v1Route({ method: 'post', path: `/broadcasts/${channel}/preview`, tag: 'Messaging', summary: `Who ${name} broadcast would reach`, access: 'supervisor', ...scope, body: loose, documented: { body: who, response: reach.extend({ event: D.anyObj.nullish(), placeholders: z.array(D.str).optional() }) }, v1: preview }); + v1Route({ method: 'post', path: `/broadcasts/${channel}/send`, tag: 'Messaging', summary: `Send ${name} broadcast`, description: 'To campuses, events, roles or listed people; news consent is checked.', access: 'supervisor', ...scope, body: loose, documented: { body: who.extend(content), response: reach }, v1: send }); + v1Route({ method: 'post', path: `/broadcasts/${channel}/schedule`, tag: 'Messaging', summary: `Schedule ${name} broadcast`, access: 'supervisor', ...scope, body: loose, documented: { body: who.extend(content).extend({ scheduledAt: D.date }), response: scheduled }, v1: schedule }); } -v1Route({ method: 'get', path: '/scheduled-messages', tag: 'Messaging', summary: 'Scheduled emails and WhatsApps', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('status', 'eventId', 'channel'), v1: sched.listScheduledEmails }); -v1Route({ method: 'patch', path: '/scheduled-messages/:id', tag: 'Messaging', summary: 'Change a scheduled message', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], params: idParams, body: loose, v1: sched.updateScheduledEmail }); -v1Route({ method: 'delete', path: '/scheduled-messages/:id', tag: 'Messaging', summary: 'Cancel a scheduled message', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], params: idParams, v1: sched.deleteScheduledEmail }); +v1Route({ method: 'get', path: '/scheduled-messages', tag: 'Messaging', summary: 'Scheduled emails and WhatsApps', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('status', 'eventId', 'channel'), documented: { response: D.obj({ jobs: z.array(scheduledJob) }) }, v1: sched.listScheduledEmails }); +v1Route({ method: 'patch', path: '/scheduled-messages/:id', tag: 'Messaging', summary: 'Change a scheduled message', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], params: idParams, body: loose, documented: { body: D.obj({ scheduledAt: D.optDate, subject: D.optStr, html: D.optStr, text: D.optStr, message: D.optStr.describe('WhatsApp') }), response: D.obj({ message: D.str, job: scheduledJob }) }, v1: sched.updateScheduledEmail }); +v1Route({ method: 'delete', path: '/scheduled-messages/:id', tag: 'Messaging', summary: 'Cancel a scheduled message', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], params: idParams, documented: { response: D.message }, v1: sched.deleteScheduledEmail }); v1Route({ method: 'post', path: '/automations/schedule', tag: 'Messaging', summary: 'Schedule an event\'s reminder messages', - access: 'supervisor', campusScope: 'scopeEvent(body.eventId)', middleware: [cs.scopeEvent({ from: (req: any) => req.body?.eventId })], body: z.looseObject({ eventId: id }), v1: auto.scheduleAutomations, + access: 'supervisor', campusScope: 'scopeEvent(body.eventId)', middleware: [cs.scopeEvent({ from: (req: any) => req.body?.eventId })], body: z.looseObject({ eventId: id }), documented: { body: D.obj({ eventId: D.str, jobs: z.array(D.obj({ scheduledAt: D.date, subject: D.str, html: D.optStr, text: D.optStr, audience: z.enum(['sponsors']).optional(), promoEventId: D.optStr })).min(1) }), response: D.obj({ message: D.str, jobs: z.array(D.anyObj) }) }, v1: auto.scheduleAutomations, }); // ─── WhatsApp connection (admins) ──────────────────────────────────────────── -v1Route({ method: 'get', path: '/whatsapp/config', tag: 'WhatsApp', summary: 'The WhatsApp connection settings', access: 'admin', v1: wa.getConfigHandler }); -v1Route({ method: 'put', path: '/whatsapp/config', tag: 'WhatsApp', summary: 'Change the WhatsApp connection settings', access: 'admin', body: loose, v1: wa.saveConfigHandler }); -v1Route({ method: 'post', path: '/whatsapp/instance', tag: 'WhatsApp', summary: 'Create the WhatsApp instance', access: 'admin', body: loose, v1: wa.createInstanceHandler }); -v1Route({ method: 'delete', path: '/whatsapp/instance', tag: 'WhatsApp', summary: 'Delete the WhatsApp instance', access: 'admin', v1: wa.deleteInstanceHandler }); -v1Route({ method: 'get', path: '/whatsapp/status', tag: 'WhatsApp', summary: 'Is WhatsApp connected?', access: 'admin', v1: wa.getStatusHandler }); -v1Route({ method: 'get', path: '/whatsapp/qr', tag: 'WhatsApp', summary: 'The QR code to link a phone', access: 'admin', v1: wa.getQrHandler }); +v1Route({ method: 'get', path: '/whatsapp/config', tag: 'WhatsApp', summary: 'The WhatsApp connection settings', access: 'admin', documented: { response: D.obj({ tokenMasked: D.str, instanceId: D.str, hasToken: D.bool, hasInstance: D.bool, configured: D.bool, webhookUrl: D.optStr }) }, v1: wa.getConfigHandler }); +v1Route({ method: 'put', path: '/whatsapp/config', tag: 'WhatsApp', summary: 'Change the WhatsApp connection settings', access: 'admin', body: loose, documented: { body: D.obj({ token: D.optStr, instanceId: D.optStr }), response: D.message }, v1: wa.saveConfigHandler }); +v1Route({ method: 'post', path: '/whatsapp/instance', tag: 'WhatsApp', summary: 'Create the WhatsApp instance', access: 'admin', body: loose, documented: { body: D.obj({ name: D.optStr }), response: D.obj({ message: D.str }).describe('Plus what the WhatsApp service answered') }, v1: wa.createInstanceHandler }); +v1Route({ method: 'delete', path: '/whatsapp/instance', tag: 'WhatsApp', summary: 'Delete the WhatsApp instance', access: 'admin', documented: { response: D.obj({ message: D.str }).describe('Plus what the WhatsApp service answered') }, v1: wa.deleteInstanceHandler }); +v1Route({ method: 'get', path: '/whatsapp/status', tag: 'WhatsApp', summary: 'Is WhatsApp connected?', access: 'admin', documented: { response: D.anyObj.describe('The WhatsApp service\'s status answer') }, v1: wa.getStatusHandler }); +v1Route({ method: 'get', path: '/whatsapp/qr', tag: 'WhatsApp', summary: 'The QR code to link a phone', access: 'admin', documented: { response: D.anyObj.describe('The WhatsApp service\'s answer, with the QR code image') }, v1: wa.getQrHandler }); for (const [action, summary, handler] of [['request-code', 'Link a phone with a code instead', wa.requestCodeHandler], ['logout', 'Unlink the phone', wa.logoutHandler], ['start', 'Start the WhatsApp session', wa.startHandler], ['restart', 'Restart the WhatsApp session', wa.restartHandler]] as const) { - v1Route({ method: 'post', path: `/whatsapp/${action}`, tag: 'WhatsApp', summary, access: 'admin', body: loose, v1: handler }); + v1Route({ + method: 'post', path: `/whatsapp/${action}`, tag: 'WhatsApp', summary, access: 'admin', body: loose, + documented: { body: action === 'request-code' ? D.obj({ phoneNumber: D.str }) : D.anyObj, response: D.anyObj.describe('The WhatsApp service\'s answer') }, + v1: handler, + }); } // ─── Banner, saved filters, dashboards, stats, analytics, reports ──────────── -v1Route({ method: 'get', path: '/banner', tag: 'Site', summary: 'The site-wide banner', access: 'public', v1: banner.getBanner }); -v1Route({ method: 'put', path: '/banner', tag: 'Site', summary: 'Set the site-wide banner', access: 'supervisor', campusScope: 'unscopedOnly (admins and unscoped supervisors)', middleware: [cs.unscopedOnly], body: loose, v1: banner.setBanner }); +v1Route({ method: 'get', path: '/banner', tag: 'Site', summary: 'The site-wide banner', access: 'public', documented: { response: bannerShape }, v1: banner.getBanner }); +v1Route({ method: 'put', path: '/banner', tag: 'Site', summary: 'Set the site-wide banner', access: 'supervisor', campusScope: 'unscopedOnly (admins and unscoped supervisors)', middleware: [cs.unscopedOnly], body: loose, documented: { body: bannerShape.partial().describe('An empty message takes the banner down'), response: bannerShape }, v1: banner.setBanner }); const OWN = 'campusIndependent (a person\'s own saved filters)'; -v1Route({ method: 'get', path: '/saved-filters', tag: 'Me', summary: 'My saved filters', description: 'For one list page (`page`).', access: 'staff', campusScope: OWN, query: filters('page'), v1: savedFilterRouter, map: ctx => ({ url: `/${qs(ctx.req)}` }) }); -v1Route({ method: 'post', path: '/saved-filters', tag: 'Me', summary: 'Save a filter', description: 'By name (replaces one with the same name); up to 30 per page.', access: 'staff', campusScope: OWN, body: loose, v1: savedFilterRouter, map: () => ({ url: '/' }) }); -v1Route({ method: 'put', path: '/saved-filters/:id', tag: 'Me', summary: 'Change a saved filter', access: 'staff', campusScope: OWN, params: idParams, body: loose, v1: savedFilterRouter, map: ctx => ({ url: `/${encodeURIComponent(ctx.params.id)}` }) }); -v1Route({ method: 'delete', path: '/saved-filters/:id', tag: 'Me', summary: 'Delete a saved filter', access: 'staff', campusScope: OWN, params: idParams, v1: savedFilterRouter, map: ctx => ({ url: `/${encodeURIComponent(ctx.params.id)}` }) }); -v1Route({ method: 'get', path: '/dashboard/today', tag: 'Dashboard', summary: 'Today at a glance', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], v1: dashboardRouter, map: ctx => ({ url: `/today${qs(ctx.req)}` }) }); -v1Route({ method: 'get', path: '/dashboard/search', tag: 'Dashboard', summary: 'Search people, registrations and events', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('q'), v1: dashboardRouter, map: ctx => ({ url: `/search${qs(ctx.req)}` }) }); -v1Route({ method: 'get', path: '/stats/staff', tag: 'Dashboard', summary: 'Staff dashboard numbers', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], v1: stats.getStaffDashboardStats }); -v1Route({ method: 'get', path: '/stats/supervisor', tag: 'Dashboard', summary: 'Supervisor dashboard numbers', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], v1: stats.getSupervisorDashboardStats }); -v1Route({ method: 'get', path: '/stats/admin', tag: 'Dashboard', summary: 'Admin dashboard numbers', access: 'admin', v1: stats.getAdminDashboardStats }); -v1Route({ method: 'get', path: '/stats/overview', tag: 'Dashboard', summary: 'Overview numbers', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('from', 'to', 'campus'), v1: stats.getOverviewStats }); +v1Route({ method: 'get', path: '/saved-filters', tag: 'Me', summary: 'My saved filters', description: 'For one list page (`page`).', access: 'staff', campusScope: OWN, query: filters('page'), documented: { response: z.array(savedFilter) }, v1: savedFilterRouter, map: ctx => ({ url: `/${qs(ctx.req)}` }) }); +v1Route({ method: 'post', path: '/saved-filters', tag: 'Me', summary: 'Save a filter', description: 'By name (replaces one with the same name); up to 30 per page.', access: 'staff', campusScope: OWN, body: loose, documented: { body: D.obj({ page: D.str, name: D.str, params: D.anyObj, isDefault: D.optBool }), response: savedFilter }, v1: savedFilterRouter, map: () => ({ url: '/' }) }); +v1Route({ method: 'put', path: '/saved-filters/:id', tag: 'Me', summary: 'Change a saved filter', access: 'staff', campusScope: OWN, params: idParams, body: loose, documented: { body: D.obj({ name: D.optStr, params: D.anyObj.optional(), isDefault: D.optBool }), response: savedFilter }, v1: savedFilterRouter, map: ctx => ({ url: `/${encodeURIComponent(ctx.params.id)}` }) }); +v1Route({ method: 'delete', path: '/saved-filters/:id', tag: 'Me', summary: 'Delete a saved filter', access: 'staff', campusScope: OWN, params: idParams, documented: { response: D.ok }, v1: savedFilterRouter, map: ctx => ({ url: `/${encodeURIComponent(ctx.params.id)}` }) }); +v1Route({ method: 'get', path: '/dashboard/today', tag: 'Dashboard', summary: 'Today at a glance', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], documented: { response: D.obj({ events: z.array(D.obj({ id: D.str, title: D.str, startsAt: D.date, endsAt: D.date, sessionLabel: D.optStr, places: D.num, checkedIn: D.num })).describe('Today\'s events with places and check-ins'), money: D.obj({ today: D.rand, todayCount: D.num, week: D.rand }).nullish(), pending: z.array(D.obj({ key: D.str, label: D.str, count: D.num, href: D.str, tone: D.optStr })).describe('What\'s waiting for you') }) }, v1: dashboardRouter, map: ctx => ({ url: `/today${qs(ctx.req)}` }) }); +v1Route({ method: 'get', path: '/dashboard/search', tag: 'Dashboard', summary: 'Search people, registrations and events', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('q'), documented: { response: D.obj({ results: z.array(D.obj({ type: D.str.describe('event, payment, person, registration'), id: D.str, title: D.str, subtitle: D.optStr, href: D.optStr })) }) }, v1: dashboardRouter, map: ctx => ({ url: `/search${qs(ctx.req)}` }) }); +v1Route({ method: 'get', path: '/stats/staff', tag: 'Dashboard', summary: 'Staff dashboard numbers', access: 'staff', campusScope: SCOPE_LIST, middleware: [cs.scopeList], documented: { response: D.obj({ scanStats, recentScans: z.array(D.anyObj) }) }, v1: stats.getStaffDashboardStats }); +v1Route({ method: 'get', path: '/stats/supervisor', tag: 'Dashboard', summary: 'Supervisor dashboard numbers', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], documented: { response: D.obj({ scanStats, recentScans: z.array(D.anyObj), paymentStats: D.anyObj, activeEventsCount: D.num }) }, v1: stats.getSupervisorDashboardStats }); +v1Route({ method: 'get', path: '/stats/admin', tag: 'Dashboard', summary: 'Admin dashboard numbers', access: 'admin', documented: { response: D.obj({ scanStats, recentScans: z.array(D.anyObj), paymentStats: D.anyObj, activeEventsCount: D.num }) }, v1: stats.getAdminDashboardStats }); +v1Route({ method: 'get', path: '/stats/overview', tag: 'Dashboard', summary: 'Overview numbers', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('from', 'to', 'campus'), documented: { response: D.obj({ funnel: D.anyObj.nullish(), activeEvents: D.num, registrations: monthly, ticketsSold: monthly, revenue: monthly, donations: monthly, trend: z.array(D.obj({ date: D.str, revenue: D.rand })), topEvents: z.array(D.obj({ eventId: D.str, title: D.str, revenue: D.rand, registrations: D.num, ticketsSold: D.num })) }) }, v1: stats.getOverviewStats }); const trackLimiter = rateLimit({ windowMs: 60 * 1000, max: 60, standardHeaders: true, legacyHeaders: false }); -v1Route({ method: 'post', path: '/analytics/track', tag: 'Dashboard', summary: 'Record a step on the way to registering', access: 'public', middleware: [trackLimiter], body: loose, v1: analytics.trackStage }); -v1Route({ method: 'get', path: '/analytics/funnel', tag: 'Dashboard', summary: 'How many get from viewing to paying', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventId', 'from', 'to'), v1: analytics.getFunnel }); -v1Route({ method: 'post', path: '/reports/pdf', tag: 'Reports', summary: 'A report as a PDF', description: 'The report\'s rows and columns in the body.', access: 'user', body: loose, file: { contentType: 'application/pdf' }, v1: reports.generatePdf }); -v1Route({ method: 'post', path: '/reports/excel', tag: 'Reports', summary: 'A report as an Excel file', access: 'user', body: loose, file: { contentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' }, v1: reports.generateExcel }); -v1Route({ method: 'post', path: '/reports/email', tag: 'Reports', summary: 'Email a report as a PDF', access: 'user', body: loose, v1: reports.emailPdf }); -v1Route({ method: 'post', path: '/reports/whatsapp', tag: 'Reports', summary: 'WhatsApp a report as a PDF', access: 'user', body: loose, v1: reports.whatsappPdf }); +v1Route({ method: 'post', path: '/analytics/track', tag: 'Dashboard', summary: 'Record a step on the way to registering', access: 'public', middleware: [trackLimiter], body: loose, documented: { body: D.obj({ sessionId: D.str.describe('The browser\'s analytics id'), eventId: D.str, stage: z.enum(['view', 'start', 'submit', 'paid']), source: D.optStr.describe('Where they came from') }), response: z.null().describe('Always 204, no content') }, v1: analytics.trackStage }); +v1Route({ method: 'get', path: '/analytics/funnel', tag: 'Dashboard', summary: 'How many get from viewing to paying', access: 'supervisor', campusScope: SCOPE_LIST, middleware: [cs.scopeList], query: filters('eventIds', 'eventId', 'from', 'to'), documented: { response: D.obj({ perEvent: z.array(D.anyObj).describe('The same for each event') }).describe('Counts per stage (view, start, submit, paid), sources and devices, and per ticket') }, v1: analytics.getFunnel }); +v1Route({ method: 'post', path: '/reports/pdf', tag: 'Reports', summary: 'A report as a PDF', description: 'The report\'s rows and columns in the body.', access: 'user', body: loose, file: { contentType: 'application/pdf' }, documented: { body: reportBody }, v1: reports.generatePdf }); +v1Route({ method: 'post', path: '/reports/excel', tag: 'Reports', summary: 'A report as an Excel file', access: 'user', body: loose, file: { contentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' }, documented: { body: reportBody }, v1: reports.generateExcel }); +v1Route({ method: 'post', path: '/reports/email', tag: 'Reports', summary: 'Email a report as a PDF', access: 'user', body: loose, documented: { body: reportBody.extend({ subject: D.optStr, body: D.optStr.describe('Text of the email') }), response: D.message }, v1: reports.emailPdf }); +v1Route({ method: 'post', path: '/reports/whatsapp', tag: 'Reports', summary: 'WhatsApp a report as a PDF', access: 'user', body: loose, documented: { body: reportBody.extend({ caption: D.optStr }), response: D.message }, v1: reports.whatsappPdf }); diff --git a/apps/events/backend/src/v2/resources/registrationsManage.ts b/apps/events/backend/src/v2/resources/registrationsManage.ts index cf9fd44..6f731f8 100644 --- a/apps/events/backend/src/v2/resources/registrationsManage.ts +++ b/apps/events/backend/src/v2/resources/registrationsManage.ts @@ -1,4 +1,5 @@ import { z } from 'zod'; +import * as D from '../docs'; import type { Request } from 'express'; import { defineRoute, type ApiUser } from '../route'; import { pageOf, single } from '../paging'; @@ -207,6 +208,16 @@ export const bulk = defineRoute({ access: 'supervisor', campusScope: 'scopeBody(registrationIds, deny orphans)', middleware: [campusScope.scopeBody([['registrationIds', 'registration']], { orphan: 'deny' })], body: z.looseObject({ action: z.enum(['markPaid', 'cancel', 'moveOption', 'allocate', 'message']), registrationIds: z.array(id).min(1).max(500) }), response: single(z.looseObject({})), + documented: { + body: D.obj({ + action: z.enum(['markPaid', 'cancel', 'moveOption', 'allocate', 'message']), registrationIds: z.array(id).min(1).max(500), + method: D.optStr.describe('markPaid: cash, eft, card or other'), paidAt: D.optDate.describe('markPaid'), + fromOptionId: D.optStr.describe('moveOption'), toOptionId: D.optStr.describe('moveOption'), + setId: D.optStr.describe('allocate'), groupId: D.optStr.describe('allocate'), + channel: z.enum(['email', 'whatsapp']).optional().describe('message'), subject: D.optStr.describe('message (email)'), text: D.optStr.describe('message'), + }), + response: D.obj({ action: D.str, done: D.num, skipped: D.num, failed: D.num, results: z.array(D.obj({ id: D.str, ok: D.bool, skipped: D.optBool, message: D.optStr })) }), + }, async handler({ body, req }) { const { runBulk } = require('../../utils/bulkRegistrations') as { runBulk(req: unknown, body: object): Promise }; return { data: plain(await runBulk(req, body)) }; diff --git a/apps/events/backend/src/v2/resources/seriesDeals.ts b/apps/events/backend/src/v2/resources/seriesDeals.ts index 75387fd..7f639a2 100644 --- a/apps/events/backend/src/v2/resources/seriesDeals.ts +++ b/apps/events/backend/src/v2/resources/seriesDeals.ts @@ -1,4 +1,5 @@ import { z } from 'zod'; +import * as D from '../docs'; import type { Request } from 'express'; import { defineRoute, type ApiUser } from '../route'; import { single } from '../paging'; @@ -74,6 +75,7 @@ export const compareSeries = defineRoute({ method: 'get', path: '/series/:id/compare', tag: 'Series', summary: 'Year on year', description: 'Registrations, tickets, income and attendance for each event in the series that you may see, oldest first.', access: 'supervisor', campusScope: 'scopeList (eventWhere in compareSeries)', params: idParams, response: single(z.looseObject({})), + documented: { response: D.obj({ series: D.anyObj, events: z.array(D.obj({ eventId: D.str, title: D.str, startDate: D.date, endDate: D.date, campus: D.anyObj.nullish(), isActive: D.bool, sessions: D.optNum, registrations: D.num, tickets: D.num, income: D.rand, checkedIn: D.num, attendanceRate: D.optNum.describe('%'), change: D.obj({ registrations: D.optNum.describe('% change from the year before'), tickets: D.optNum.describe('% change from the year before'), income: D.optNum.describe('% change from the year before'), checkedIn: D.optNum.describe('% change from the year before') }).nullable() })) }) }, async handler({ params, req }) { return { data: plain(await series.compareSeries(params.id, await ctxOf(req))) }; }, }); @@ -137,6 +139,7 @@ export const buyPass = defineRoute({ description: 'Registers you at every event on it, then answers with a checkout to pay (or issues the tickets when it\'s free).', access: 'user', status: 201, params: idParams, body: z.object({ quantity: z.number().int().min(1).max(50).default(1), provider: z.string().max(40).optional() }), + documented: { response: D.obj({ purchaseId: D.str, total: D.rand, paid: D.bool.describe('Free: the tickets are issued straight away'), redirectUrl: D.optStr.describe('Where to send them to pay'), provider: D.optStr, message: D.optStr }) }, response: single(z.looseObject({})), async handler({ params, body, user }) { return { data: plain(await series.buyPass(params.id, user!.id, body)) }; }, }); @@ -144,6 +147,7 @@ export const buyPass = defineRoute({ export const payPass = defineRoute({ method: 'post', path: '/season-pass-purchases/:id/checkout', tag: 'Series', summary: 'Pay what\'s owed on a pass', access: 'user', params: idParams, body: z.object({ provider: z.string().max(40).optional() }), response: single(z.looseObject({})), + documented: { response: D.obj({ redirectUrl: D.optStr, provider: D.optStr, message: D.optStr }) }, async handler({ params, body, user }) { return { data: plain(await series.payPassPurchase(params.id, user!.id, body)) }; }, }); diff --git a/apps/events/backend/src/v2/route.ts b/apps/events/backend/src/v2/route.ts index 568a6a3..5682cb0 100644 --- a/apps/events/backend/src/v2/route.ts +++ b/apps/events/backend/src/v2/route.ts @@ -57,6 +57,13 @@ export type RouteDef

, Infer, Infer>) => Promise> | z.input; }; @@ -89,6 +96,15 @@ export function defineRoute

(schema: S, value: unknown): Infer => (schema ? schema.parse(value) : undefined) as Infer; +/** Outside production: says when a documented-only body or answer doesn't fit its documentation. */ +function warnUndocumented(def: AnyRoute, what: string, schema: Schema, value: unknown) { + if (process.env.NODE_ENV === 'production') return; + const checked = schema.safeParse(value); + if (!checked.success) { + console.warn(`[api/v2] ${def.method.toUpperCase()} ${def.path}: ${what} doesn't match its documented schema`, JSON.stringify(checked.error.issues.slice(0, 5))); + } +} + /** Adds every defined route to the router. */ export function mount(router: Router, list: AnyRoute[] = routes): void { for (const def of list) { @@ -102,7 +118,9 @@ export function mount(router: Router, list: AnyRoute[] = routes): void { req, res, }; + if (def.documented?.body) warnUndocumented(def, 'request body', def.documented.body, req.body ?? {}); const result = await def.handler(ctx); + if (def.documented?.response) warnUndocumented(def, 'answer', def.documented.response, (result as { data?: unknown })?.data); 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); diff --git a/apps/events/backend/src/v2/viaV1.ts b/apps/events/backend/src/v2/viaV1.ts index 60b1cf1..3ac10de 100644 --- a/apps/events/backend/src/v2/viaV1.ts +++ b/apps/events/backend/src/v2/viaV1.ts @@ -152,6 +152,8 @@ type V1RouteDef = { query?: z.ZodType; body?: z.ZodType; response?: z.ZodType; + /** The body and the answer's `data`, for the docs only (see RouteDef.documented). */ + documented?: { body?: z.ZodType; response?: z.ZodType }; status?: number; file?: { contentType: string }; upload?: { field: string; description: string }; diff --git a/apps/events/backend/tests/corrections.test.ts b/apps/events/backend/tests/corrections.test.ts new file mode 100644 index 0000000..da18736 --- /dev/null +++ b/apps/events/backend/tests/corrections.test.ts @@ -0,0 +1,195 @@ +/** + * 1.52.0: tickets no longer go missing at the door. A required attendee form only holds tickets + * back until it's filled in or left for later, picked-session bookings need one form per person + * (not per session), a form with no questions holds nothing back, and admins can issue tickets + * unpaid, make a balance free and check people in after the event (services/corrections.ts). + */ +const mockDb: any = { + registration: { findUnique: jest.fn(), findMany: jest.fn(), update: jest.fn() }, + registrationOption: { findMany: jest.fn(), findUnique: jest.fn(), update: jest.fn(), delete: jest.fn() }, + eventForm: { findUnique: jest.fn() }, + formResponse: { count: jest.fn() }, + ticket: { create: jest.fn(), update: jest.fn(), deleteMany: jest.fn(), findMany: jest.fn(), findUnique: jest.fn() }, + ticketUsage: { create: jest.fn(), deleteMany: jest.fn(), findMany: jest.fn() }, + eventSession: { findUnique: jest.fn() }, + event: { findUnique: jest.fn() }, +}; +jest.mock('../src/config/db', () => mockDb); +const mockAudit = jest.fn(); +jest.mock('../src/utils/adminAudit', () => ({ logAdminAction: (...a: unknown[]) => mockAudit(...a) })); +const mockReminder = jest.fn(async () => ['email']); +jest.mock('../src/utils/notifications', () => ({ sendFormReminderMessage: (...a: unknown[]) => (mockReminder as jest.Mock)(...a) })); +const mockEmailTickets = jest.fn(async () => undefined); +jest.mock('../src/controllers/ticketController', () => ({ emailTickets: (...a: unknown[]) => (mockEmailTickets as jest.Mock)(...a) })); +jest.mock('../src/utils/cashupUtils', () => ({ assertEventOpen: jest.fn(async () => undefined) })); +const mockRecalc = jest.fn(async () => 0); +jest.mock('../src/utils/coupons', () => ({ recalculateRegistrationDiscount: (...a: unknown[]) => (mockRecalc as jest.Mock)(...a) })); +const mockDue = jest.fn(() => 300); +jest.mock('../src/utils/pricing', () => ({ computeRegistrationTotalDue: (...a: unknown[]) => (mockDue as jest.Mock)(...a) })); + +// eslint-disable-next-line @typescript-eslint/no-require-imports +const tickets = require('../src/utils/ticketUtils'); +import * as corrections from '../src/services/corrections'; + +const admin = { actor: { id: 'adm', role: 'admin' }, ip: '1.2.3.4' }; +const main = { isMainTicket: true }; +const QUESTION_FORM = { isRequired: true, fields: [{ type: 'statement' }, { type: 'text' }] }; + +/** A registration as generateTicketsForRegistration loads it: one line of `qty` main tickets. */ +const reg = (extra: object = {}, qty = 2) => ({ + id: 'r1', userId: 'u1', eventId: 'ev1', status: 'paid', formWaivedAt: null, ticketsReleasedAt: null, + registrationOptions: [{ id: 'ro1', eventOptionId: 'adult', variantId: null, sessionId: null, quantity: qty, eventOption: main, tickets: [] }], + ...extra, +}); + +beforeEach(() => { + jest.clearAllMocks(); + mockDb.eventForm.findUnique.mockResolvedValue(null); + mockDb.formResponse.count.mockResolvedValue(0); + mockDb.registrationOption.findMany.mockResolvedValue([{ id: 'ro1', quantity: 2, tickets: [], attendees: [] }]); + mockDb.ticket.create.mockImplementation(async ({ data }: any) => data); +}); + +describe('which forms hold tickets back', () => { + test('a picked-session booking counts its people once, not once per session', () => { + const lines = [ + { eventOptionId: 'day', variantId: null, sessionId: 's1', quantity: 2, eventOption: main }, + { eventOptionId: 'day', variantId: null, sessionId: 's2', quantity: 2, eventOption: main }, + { eventOptionId: 'day', variantId: null, sessionId: 's3', quantity: 1, eventOption: main }, + { eventOptionId: 'adult', variantId: null, sessionId: null, quantity: 3, eventOption: main }, + { eventOptionId: 'tshirt', variantId: null, sessionId: null, quantity: 4, eventOption: { isMainTicket: false } }, + ]; + expect(tickets.formPlaces(lines)).toBe(5); + }); + + test('only a required form with a question to answer counts', () => { + expect(tickets.formNeedsAnswers(QUESTION_FORM)).toBe(true); + expect(tickets.formNeedsAnswers({ isRequired: true, fields: [{ type: 'statement' }, { type: 'paragraph' }] })).toBe(false); + expect(tickets.formNeedsAnswers({ isRequired: false, fields: [{ type: 'text' }] })).toBe(false); + expect(tickets.formNeedsAnswers(null)).toBe(false); + }); + + test('forms still needed: places less the forms in; none once left for later', async () => { + mockDb.eventForm.findUnique.mockResolvedValue(QUESTION_FORM); + mockDb.formResponse.count.mockResolvedValue(1); + expect(await tickets.formsOutstanding(reg({}, 3))).toBe(2); + expect(await tickets.formsOutstanding(reg({ formWaivedAt: new Date() }, 3))).toBe(0); + }); +}); + +describe('generating tickets', () => { + test('a required form not filled in holds them back', async () => { + mockDb.registration.findUnique.mockResolvedValue(reg()); + mockDb.eventForm.findUnique.mockResolvedValue(QUESTION_FORM); + expect(await tickets.generateTicketsForRegistration('r1')).toEqual([]); + expect(mockDb.ticket.create).not.toHaveBeenCalled(); + }); + + test('…until the form is left for later', async () => { + mockDb.registration.findUnique.mockResolvedValue(reg({ formWaivedAt: new Date() })); + mockDb.eventForm.findUnique.mockResolvedValue(QUESTION_FORM); + expect(await tickets.generateTicketsForRegistration('r1')).toHaveLength(1); + }); + + test('a form with only statements and headings holds nothing back', async () => { + mockDb.registration.findUnique.mockResolvedValue(reg()); + mockDb.eventForm.findUnique.mockResolvedValue({ isRequired: true, fields: [{ type: 'statement' }] }); + expect(await tickets.generateTicketsForRegistration('r1')).toHaveLength(1); + }); + + test('unpaid: none, unless an admin released them (and never when cancelled)', async () => { + mockDb.registration.findUnique.mockResolvedValueOnce(reg({ status: 'pending' })); + expect(await tickets.generateTicketsForRegistration('r1')).toEqual([]); + mockDb.registration.findUnique.mockResolvedValueOnce(reg({ status: 'partial_paid', ticketsReleasedAt: new Date() })); + expect(await tickets.generateTicketsForRegistration('r1')).toHaveLength(1); + mockDb.registration.findUnique.mockResolvedValueOnce(reg({ status: 'cancelled', ticketsReleasedAt: new Date() })); + expect(await tickets.generateTicketsForRegistration('r1')).toEqual([]); + }); +}); + +describe('Fill in later', () => { + test('stops the tickets waiting, issues and sends them, and sends the form link', async () => { + let waived: Date | null = null; + mockDb.registration.findUnique.mockImplementation(async () => reg({ formWaivedAt: waived })); + mockDb.registration.update.mockImplementation(async ({ data }: any) => { waived = data.formWaivedAt; }); + mockDb.eventForm.findUnique.mockResolvedValue(QUESTION_FORM); + const out = await corrections.leaveFormForLater('r1', { actor: { id: 'st', role: 'staff' } }); + expect(waived).toBeInstanceOf(Date); + expect(out).toEqual({ ticketsIssued: 1, sentTo: ['email'] }); + expect(mockEmailTickets).toHaveBeenCalledTimes(1); + expect(mockReminder).toHaveBeenCalledWith('r1'); + expect(mockAudit).toHaveBeenCalledWith(expect.objectContaining({ action: 'attendee_form_waived', targetId: 'r1' })); + }); +}); + +describe('issuing tickets as an admin', () => { + test('unpaid needs "pay later"', async () => { + mockDb.registration.findUnique.mockResolvedValue(reg({ status: 'pending' })); + await expect(corrections.issueTickets('r1', admin, {})).rejects.toThrow('isn\'t paid yet'); + }); + + test('a form still outstanding is refused unless it\'s left for later — and nothing is changed', async () => { + mockDb.registration.findUnique.mockResolvedValue(reg({ status: 'pending' })); + mockDb.eventForm.findUnique.mockResolvedValue(QUESTION_FORM); + await expect(corrections.issueTickets('r1', admin, { payLater: true })).rejects.toThrow('2 attendee forms are still to fill in'); + expect(mockDb.registration.update).not.toHaveBeenCalled(); + }); + + test('pay later releases them with the balance still owed', async () => { + mockDb.registration.findUnique.mockResolvedValue(reg({ status: 'pending' })); + mockDb.event.findUnique.mockResolvedValue({ id: 'ev1', scheduleType: 'single', sessions: [], form: null }); + await corrections.issueTickets('r1', admin, { payLater: true, reason: 'Pays on Friday' }).catch(() => undefined); + expect(mockDb.registration.update).toHaveBeenCalledWith(expect.objectContaining({ data: expect.objectContaining({ ticketsReleasedAt: expect.any(Date), ticketsReleasedById: 'adm' }) })); + expect(mockDb.registration.update.mock.calls[0][0].data.status).toBeUndefined(); + expect(mockAudit).toHaveBeenCalledWith(expect.objectContaining({ action: 'tickets_issued_override', metadata: expect.objectContaining({ payLater: true, reason: 'Pays on Friday' }) })); + }); + + test('make it free writes the balance off as a discount and marks it paid', async () => { + mockDb.registration.findUnique.mockImplementation(async (q: any) => (q.include?.payments + ? { ...reg({ status: 'partial_paid' }), complimentaryDiscount: 0, payments: [{ amount: 100 }] } + : reg({ status: 'partial_paid' }))); + mockDb.event.findUnique.mockResolvedValue({ id: 'ev1', scheduleType: 'single', sessions: [], form: null }); + const out = await corrections.makeComplimentary('r1', admin, { reason: 'Speaker' }).catch((e: Error) => e); + expect(mockDb.registration.update).toHaveBeenCalledWith(expect.objectContaining({ data: expect.objectContaining({ complimentaryDiscount: 200 }) })); + expect(mockRecalc).toHaveBeenCalledWith('r1'); + expect(mockDb.registration.update).toHaveBeenCalledWith(expect.objectContaining({ data: expect.objectContaining({ status: 'paid' }) })); + expect(mockAudit).toHaveBeenCalledWith(expect.objectContaining({ action: 'registration_complimentary', metadata: expect.objectContaining({ amount: 200 }) })); + expect(out).toMatchObject({ amount: 200 }); + }); +}); + +describe('check-in after the event', () => { + const ticket = (extra: object = {}) => ({ + id: 't1', eventId: 'ev1', quantity: 2, usages: [], event: { id: 'ev1', scheduleType: 'single' }, + registrationOption: { sessionId: null, sessionIds: [], registration: { status: 'paid' } }, ...extra, + }); + + test('checks everyone left in as a manual check-in, with no window or closed-event check', async () => { + mockDb.ticket.findUnique.mockResolvedValue(ticket({ usages: [{ id: 'u0', quantityRedeemed: 1, sessionId: null }] })); + mockDb.ticketUsage.findMany.mockResolvedValue([{ quantityRedeemed: 1, sessionId: null }, { quantityRedeemed: 1, sessionId: null }]); + const out = await corrections.correctCheckIn('t1', admin, {}); + expect(mockDb.ticketUsage.create).toHaveBeenCalledWith({ data: { ticketId: 't1', scannedById: 'adm', quantityRedeemed: 1, sessionId: null, manual: true } }); + expect(mockDb.ticket.update).toHaveBeenCalledWith(expect.objectContaining({ data: expect.objectContaining({ isUsed: true }) })); + expect(out).toEqual({ checkedIn: 2, quantity: 2 }); + expect(mockAudit).toHaveBeenCalledWith(expect.objectContaining({ action: 'checkin_corrected' })); + }); + + test('undo removes the check-ins; a full ticket can\'t be checked in again', async () => { + mockDb.ticket.findUnique.mockResolvedValue(ticket({ usages: [{ id: 'u0', quantityRedeemed: 2, sessionId: null }] })); + await expect(corrections.correctCheckIn('t1', admin, {})).rejects.toThrow('already checked in'); + mockDb.ticketUsage.findMany.mockResolvedValue([]); + await corrections.correctCheckIn('t1', admin, { present: false }); + expect(mockDb.ticketUsage.deleteMany).toHaveBeenCalledWith({ where: { id: { in: ['u0'] } } }); + }); + + test('multi-day: the session must be the event\'s and on the ticket', async () => { + mockDb.ticket.findUnique.mockResolvedValue(ticket({ event: { id: 'ev1', scheduleType: 'sessions' }, registrationOption: { sessionId: 's1', sessionIds: [], registration: { status: 'paid' } } })); + await expect(corrections.correctCheckIn('t1', admin, {})).rejects.toThrow('Choose one of this event'); + mockDb.eventSession.findUnique.mockResolvedValue({ id: 's2', eventId: 'ev1', cancelledAt: null }); + await expect(corrections.correctCheckIn('t1', admin, { sessionId: 's2' })).rejects.toThrow('isn\'t booked for this session'); + mockDb.eventSession.findUnique.mockResolvedValue({ id: 's1', eventId: 'ev1', cancelledAt: null }); + mockDb.ticketUsage.findMany.mockResolvedValue([{ quantityRedeemed: 2, sessionId: 's1' }]); + await corrections.correctCheckIn('t1', admin, { sessionId: 's1' }); + expect(mockDb.ticketUsage.create).toHaveBeenCalledWith({ data: expect.objectContaining({ sessionId: 's1', manual: true, quantityRedeemed: 2 }) }); + }); +}); diff --git a/apps/events/backend/tests/v2Docs.test.ts b/apps/events/backend/tests/v2Docs.test.ts new file mode 100644 index 0000000..92af90b --- /dev/null +++ b/apps/events/backend/tests/v2Docs.test.ts @@ -0,0 +1,109 @@ +import express from 'express'; +import request from 'supertest'; +import { z } from 'zod'; + +// 1.52.1: the API document describes every route. Routes answered by a v1 handler carry +// `documented` shapes — in the document, never enforced, and logged outside production when the +// real body or answer doesn't fit them. + +jest.mock('../src/middleware/authMiddleware', () => ({ + protect: (_req: unknown, _res: unknown, next: () => void) => next(), + optionalAuth: (_req: unknown, _res: unknown, next: () => void) => next(), + admin: (_req: unknown, _res: unknown, next: () => void) => next(), + staff: (_req: unknown, _res: unknown, next: () => void) => next(), + supervisor: (_req: unknown, _res: unknown, next: () => void) => next(), + loginLimiter: (_req: unknown, _res: unknown, next: () => void) => next(), +})); + +import { defineRoute, mount } from '../src/v2/route'; +import { buildOpenApi } from '../src/v2/openapi'; +import { errorHandler } from '../src/v2/errors'; + +const documented = defineRoute({ + method: 'post', path: '/docs-test/things', tag: 'Test', summary: 'Make a thing', access: 'public', + body: z.looseObject({}), + response: z.object({ data: z.unknown() }), + documented: { body: z.object({ name: z.string() }), response: z.object({ id: z.string(), name: z.string() }) }, + handler: ({ req }) => ({ data: (req.body as { name?: unknown }).name === 'odd' ? { id: 1 } : { id: 't1', name: String((req.body as { name?: unknown }).name) } }), +}); +const action = defineRoute({ + method: 'post', path: '/docs-test/things/:id/poke', tag: 'Test', summary: 'Poke a thing', access: 'public', + params: z.object({ id: z.string() }), query: z.looseObject({ from: z.string().optional() }), body: z.looseObject({}), response: z.object({ data: z.unknown() }), + handler: () => ({ data: null }), +}); + +const app = express(); +app.use(express.json()); +const router = express.Router(); +mount(router, [documented, action]); +router.use(errorHandler); +app.use('/api/v2', router); + +describe('documented shapes', () => { + const doc = buildOpenApi({ version: 'test', list: [documented, action] }) as any; + const op = doc.paths['/docs-test/things'].post; + + test('are what the document shows, in place of the generic body and answer', () => { + expect(op.requestBody.required).toBe(true); + expect(op.requestBody.content['application/json'].schema.properties.name).toEqual({ type: 'string' }); + expect(op.responses['200'].content['application/json'].schema.properties.data.properties).toEqual({ id: { type: 'string' }, name: { type: 'string' } }); + }); + + test('an action with no input says it needs no body; parameters get their common description', () => { + const poke = doc.paths['/docs-test/things/{id}/poke'].post; + expect(poke.requestBody).toMatchObject({ required: true, description: expect.stringContaining('No body needed') }); + expect(poke.parameters).toEqual(expect.arrayContaining([ + expect.objectContaining({ name: 'id', in: 'path', description: 'The id' }), + expect.objectContaining({ name: 'from', in: 'query', description: expect.stringContaining('On or after') }), + ])); + }); + + test('are never enforced: a body or answer that doesn\'t fit still goes through, and is logged', async () => { + const warn = jest.spyOn(console, 'warn').mockImplementation(() => undefined); + const fits = await request(app).post('/api/v2/docs-test/things').send({ name: 'Bob' }); + expect(fits.status).toBe(200); + expect(warn).not.toHaveBeenCalled(); + + const odd = await request(app).post('/api/v2/docs-test/things').send({ name: 'odd' }); + expect(odd.status).toBe(200); + expect(odd.body).toEqual({ data: { id: 1 } }); + const noName = await request(app).post('/api/v2/docs-test/things').send({}); + expect(noName.status).toBe(200); + expect(warn.mock.calls.map(c => c[0])).toEqual([ + expect.stringContaining('answer doesn\'t match its documented schema'), + expect.stringContaining('request body doesn\'t match its documented schema'), + ]); + warn.mockRestore(); + }); +}); + +describe('the whole API document', () => { + // eslint-disable-next-line @typescript-eslint/no-require-imports + require('../src/v2'); + const doc = buildOpenApi({ version: 'test' }) as any; + // (Leaving out this file's own test routes.) + const ops = Object.entries(doc.paths).filter(([path]) => !path.startsWith('/docs-test')).flatMap(([path, methods]) => Object.entries(methods).map(([method, op]) => ({ path, method, op }))); + const isBlank = (s: any) => !s || Object.keys(s).length === 0 || (s.type === 'object' && !s.properties && !s.additionalProperties && !s.description); + + test('every JSON answer says what\'s in it', () => { + const blank = ops.filter(({ op }) => { + const json = Object.entries(op.responses).find(([code]) => code.startsWith('2'))?.[1]?.content?.['application/json']; + if (!json) return false; + const data = json.schema?.properties?.data; + return isBlank(data) || (data?.type === 'array' && isBlank(data.items)); + }).map(({ method, path }) => `${method.toUpperCase()} ${path}`); + // A JSON file download (my data) is the one answer that's a file, not a shape. + expect(blank).toEqual(['GET /me/privacy/export']); + }); + + test('every body that takes something says what, and every parameter is described', () => { + const undescribed = ops.flatMap(({ method, path, op }) => op.parameters.filter((p: any) => !p.description).map((p: any) => `${method} ${path} ${p.in}:${p.name}`)); + expect(undescribed).toEqual([]); + const bodies = ops.filter(({ op }) => op.requestBody?.content?.['application/json']); + for (const { op } of bodies) { + const schema = op.requestBody.content['application/json'].schema; + const takesSomething = (!!schema.properties && Object.keys(schema.properties).length > 0) || !!schema.additionalProperties?.type || !!schema.description; + if (!takesSomething) expect(op.requestBody.description).toMatch(/No body needed/); + } + }); +}); diff --git a/apps/events/docs/HANDOVER.md b/apps/events/docs/HANDOVER.md index c0cc183..f6e9331 100644 --- a/apps/events/docs/HANDOVER.md +++ b/apps/events/docs/HANDOVER.md @@ -1,6 +1,6 @@ # Handover — where things stand and how to carry on -Last updated: 2026-10-30, after **1.51.17** and Hub **1.6.0**; 2.0.0 in progress on `release/2.0`. The plan itself is in +Last updated: 2026-11-02, after **1.52.1** and Hub **1.6.0**; 2.0.0 in progress on `release/2.0`. The plan itself is in [ROADMAP-v2.md](./ROADMAP-v2.md) (decisions table at the end); the previous round of features is in [FEATURES-ROUND-1.md](./FEATURES-ROUND-1.md). @@ -14,6 +14,8 @@ encrypted settings unreadable or break existing installs. | Version | What | |---------|------| +| 1.52.1 | **API documentation complete:** every v2 route documents its body, answer and parameters — the ~300 answered by v1 handlers through `documented` shapes (`src/v2/docs.ts`), shown but not enforced, logged outside production when they don't fit; empty bodies say "No body needed". Test `tests/v2Docs.test.ts` | +| 1.52.0 | **Urgent fix + Corrections:** required attendee forms no longer leave paid door/manual registrations without tickets — popup with "Fill in later" (`Registration.formWaivedAt`, `POST /api/v2/registrations/{id}/form-later`); one form per person on picked sessions; forms with no questions don't hold tickets; kiosk asks for the forms the server says are missing. Admin **Corrections** page (`src/services/corrections.ts`, `/api/v2/corrections/…`): issue missing tickets, pay later (`ticketsReleasedAt`), make it free (`complimentaryDiscount`), check in after the event. Migration `20261102120000_corrections`. e2e `e2e/corrections.spec.ts` | | 1.51.17 | **Security:** forgot-password and sign-in don't reveal whether an account exists (same answer, status and timing); forgot-password rate-limited | | 1.51.16 | **Incoming webhooks and message links on v2** — `src/v2/links.ts` (`/api/v2/webhooks/…`, one-click unsubscribe, 308s for old links); provider URLs and email links point at v2 | | 1.51.15 | **Privacy and admin on v2** — `resources/adminPrivacy.ts`; every frontend call on v2; impersonation end/log allowed on v2 while read-only | @@ -510,6 +512,16 @@ Languages (Afrikaans, §10) and Wallet passes (§7) are removed from scope (2026 - Body and query schemas are loose (`z.looseObject`) and v1 gets the request as sent, so v2 refuses nothing v1 accepted. Give a `query` schema for filters the frontend passes — the typed `apiV2` only allows declared ones. +- **Document every v1Route (1.52.1):** `documented: { body?, response? }` with the shapes from + `src/v2/docs.ts` (`D.obj`, `D.payment`, `D.message`…) — the body it reads and the `data` it answers. + They go in the OpenAPI document but are **not enforced** (the handler still gets what was sent and + its answer goes out as it is), so a mistake can't break a screen. Outside production a body or + answer that doesn't fit is logged as `[api/v2] … doesn't match its documented schema` — grep the + e2e output for it after changing a handler. `tests/v2Docs.test.ts` fails if a JSON answer is + undocumented or a parameter has no description (common query names are described once in + `QUERY_HELP`, path ones in `PATH_HELP`). An action that takes no input keeps `body: loose`; the + document says "No body needed". Because the frontend's types come from the document, a documented + shape that's wrong usually shows up as a frontend type error too. - Moving these handlers into TS services (as 1.51.1 – 1.51.10 did) is a later clean-up; the v2 API doesn't change when it happens. - Frontend conversions are scripted from `SUCCESSORS` and the OpenAPI document (scratch tool, not diff --git a/apps/events/e2e/corrections.spec.ts b/apps/events/e2e/corrections.spec.ts new file mode 100644 index 0000000..67b58ab --- /dev/null +++ b/apps/events/e2e/corrections.spec.ts @@ -0,0 +1,126 @@ +import { test, expect, loginAs, api, seed, pickEvent } from "./fixtures"; +import type { Page } from "@playwright/test"; + +// 1.52.0: a required attendee form no longer leaves paid door registrations without tickets, +// and admins can put things right afterwards (Corrections). + +type Reg = { id: string; status: string; formsNeeded?: number; registrationOptions: { tickets?: { id: string }[] }[] }; +type Row = { id: string; user: { name: string }; missingTickets: boolean; formsNeeded: number; balance: number; status: string; tickets: { id: string; checkedIn: Record }[] }; + +const ticketsOn = (r: Reg) => r.registrationOptions.reduce((n, o) => n + (o.tickets || []).length, 0); + +async function register(page: Page, name: string, email: string): Promise { + const res = await api<{ data: Reg }>(page, "supervisor", "POST", "/api/v2/registrations/manual", { + eventId: seed().events.form, options: [{ eventOptionId: seed().formOptionId, quantity: 1 }], + user: { name, email }, skipActivationNotice: true, + }); + return res.data; +} +const full = async (page: Page, id: string) => (await api<{ data: Reg }>(page, "supervisor", "GET", `/api/v2/registrations/${id}/full`)).data; +const pay = (page: Page, id: string, amount = 200) => api<{ data: { formsNeeded?: number } }>(page, "supervisor", "POST", "/api/v2/payments", { registrationId: id, amount, method: "cash" }); +const rows = async (page: Page, eventId: string) => (await api<{ data: { registrations: Row[] } }>(page, "admin", "GET", `/api/v2/corrections/events/${eventId}`)).data.registrations; + +test.describe("required attendee forms at the door", () => { + test("paid at the door: the form holds the tickets back until it's filled in or left for later", async ({ page }) => { + const reg = await register(page, "Door Formless", "door-formless@e2e.test"); + expect(reg.formsNeeded).toBe(1); + const paid = await pay(page, reg.id); + expect(paid.data.formsNeeded).toBe(1); + expect(ticketsOn(await full(page, reg.id))).toBe(0); + + const later = await api<{ data: { ticketsIssued: number } }>(page, "staff", "POST", `/api/v2/registrations/${reg.id}/form-later`, { notify: false }); + expect(later.data.ticketsIssued).toBe(1); + expect(ticketsOn(await full(page, reg.id))).toBe(1); + }); + + test("at the door the form pops up; filling it in issues the tickets once paid", async ({ page }) => { + await loginAs(page, "supervisor"); + await page.goto("/dashboard/supervisor/at-the-door"); + await page.waitForLoadState("networkidle"); + await pickEvent(page, "E2E Camp Weekend"); + await page.waitForLoadState("networkidle"); + + await page.getByPlaceholder("Name, email or phone…").fill("Door Camper"); + await page.getByText('New attendee "Door Camper"…').click(); + await page.getByPlaceholder("Email address").fill("door-camper@e2e.test"); + await page.getByRole("button", { name: "Next — Choose Items" }).click(); + await page.getByRole("button", { name: "Confirm Registration" }).click(); + + const popup = page.getByRole("dialog", { name: /Attendee form/ }); + await expect(popup).toBeVisible(); + await expect(popup.getByText("About you")).toBeVisible(); + await popup.getByRole("button", { name: "Save form" }).click(); + await expect(popup.getByText('"Emergency contact" is required.')).toBeVisible(); + await popup.getByLabel(/Emergency contact/).fill("Mom 082 000 0000"); + await popup.getByRole("button", { name: "Save form" }).click(); + await expect(popup).toBeHidden(); + await expect(page.getByText("Attendee form saved.")).toBeVisible(); + + await page.getByRole("button", { name: "Full" }).click(); + await page.getByRole("button", { name: "Capture Payment" }).click(); + await expect(page.getByText("Payment recorded — tickets sent.")).toBeVisible(); + await expect(page.getByRole("button", { name: /^Check In 1/ })).toBeVisible(); + }); + + test("self-service kiosk: the visitor fills in the form and is registered", async ({ page }) => { + await page.goto("/self-service"); + await page.getByPlaceholder("supervisor@example.com").fill(seed().users.supervisor.email); + await page.getByPlaceholder("••••••••").fill("E2e-password-123"); + await page.getByRole("button", { name: "Sign In" }).click(); + await pickEvent(page, "E2E Camp Weekend"); + await page.getByRole("button", { name: "Start Kiosk" }).click(); + + await page.getByPlaceholder("john@example.com").fill("kiosk-camper@e2e.test"); + await page.getByPlaceholder("John Smith").fill("Kiosk Camper"); + await page.getByRole("button", { name: /^Add one / }).first().click(); + await page.getByRole("button", { name: "Next — Fill in Form" }).click(); + await expect(page.getByRole("heading", { name: "Attendee Information" })).toBeVisible(); + // A heading is text to read, not a box to fill in. + await expect(page.getByText("About you")).toBeVisible(); + await expect(page.locator("textarea")).toHaveCount(0); + await page.getByLabel(/Emergency contact/).fill("Dad 082 111 1111"); + await page.getByRole("button", { name: "Complete Registration" }).click(); + await expect(page.getByRole("heading", { name: "You're Registered!" })).toBeVisible(); + }); +}); + +test.describe("Corrections (admins)", () => { + test("issue every missing ticket at an event in one go", async ({ page }) => { + const reg = await register(page, "Missing Tickets", "missing-tickets@e2e.test"); + await pay(page, reg.id); + expect((await rows(page, seed().events.form)).find(r => r.id === reg.id)).toMatchObject({ missingTickets: true, formsNeeded: 1 }); + + const out = await api<{ data: { registrations: number; tickets: number } }>(page, "admin", "POST", `/api/v2/corrections/events/${seed().events.form}/issue-missing`, {}); + expect(out.data.tickets).toBeGreaterThanOrEqual(1); + expect((await rows(page, seed().events.form)).find(r => r.id === reg.id)).toMatchObject({ missingTickets: false, formsNeeded: 0 }); + }); + + test("tickets before payment, and making a balance free", async ({ page }) => { + const later = await register(page, "Pays Later", "pays-later@e2e.test"); + const res = await api<{ data: { ticketsIssued: number; registration: Row } }>(page, "admin", "POST", `/api/v2/corrections/registrations/${later.id}/tickets`, { payLater: true, skipForm: true, reason: "Pays on Friday" }); + expect(res.data.ticketsIssued).toBe(1); + expect(res.data.registration).toMatchObject({ status: "pending", balance: 200 }); + + const comp = await register(page, "On The House", "on-the-house@e2e.test"); + await pay(page, comp.id, 50); + const free = await api<{ data: { amount: number; registration: Row } }>(page, "admin", "POST", `/api/v2/corrections/registrations/${comp.id}/complimentary`, { skipForm: true, reason: "Speaker" }); + expect(free.data.amount).toBe(150); + expect(free.data.registration).toMatchObject({ status: "paid", balance: 0 }); + expect(free.data.registration.tickets).toHaveLength(1); + + // Not for staff or supervisors. + await expect(api(page, "supervisor", "GET", `/api/v2/corrections/events/${seed().events.form}`)).rejects.toThrow("403"); + }); + + test("check someone in after the event is over", async ({ page }) => { + await loginAs(page, "admin"); + await page.goto(`/dashboard/admin/corrections?event=${seed().events.past}`); + await page.getByRole("button", { name: /^Not checked in/ }).click(); + const card = page.locator("div.border.rounded-xl", { hasText: "Lerato Late" }); + await expect(card.getByText("Checked in: 0/2")).toBeVisible(); + await card.getByRole("button", { name: "Check in" }).click(); + await expect(page.getByText("Lerato Late: checked in.")).toBeVisible(); + const [row] = (await rows(page, seed().events.past)).filter(r => r.user.name === "Lerato Late"); + expect(row.tickets[0].checkedIn.event).toBe(2); + }); +}); diff --git a/apps/events/e2e/fixtures.ts b/apps/events/e2e/fixtures.ts index fe621a9..80245ca 100644 --- a/apps/events/e2e/fixtures.ts +++ b/apps/events/e2e/fixtures.ts @@ -5,9 +5,10 @@ import path from "path"; export type Role = "admin" | "supervisor" | "staff" | "user"; export type Seed = { users: Record; - events: { free: string; paid: string; course: string; dropIn: string; conference: string; kids: string; serving: string }; + events: { free: string; paid: string; course: string; dropIn: string; conference: string; kids: string; serving: string; form: string; past: string }; campuses: Record<"north" | "south", { id: string; slug: string }>; northTicketQr: string; + formOptionId: string; course: { sessions: { id: string; label: string }[]; ticketId: string; qrCode: string }; unsubscribeToken: string; newsPromptUser: { id: string; token: string }; diff --git a/apps/events/e2e/support/prepare-db.js b/apps/events/e2e/support/prepare-db.js index f8b7367..70679f0 100644 --- a/apps/events/e2e/support/prepare-db.js +++ b/apps/events/e2e/support/prepare-db.js @@ -187,11 +187,43 @@ async function seed(url) { await generateTicketsForRegistration(northReg.id); const northTicket = await prisma.ticket.findFirst({ where: { registrationOption: { registrationId: northReg.id } } }); + // Corrections (corrections.spec.ts): a paid camp with a required attendee form, and an event + // that ended yesterday with someone who was never checked in. Hidden, like kids/serving. + const formEvent = await prisma.event.create({ + data: { + title: 'E2E Camp Weekend', description: 'A camp with a required attendee form.', startDate: at(5, 7), endDate: at(6, 15), + price: 200, isHidden: true, createdById: users.supervisor.id, + eventOptions: { create: [{ name: 'Camp ticket', price: 200, isMainTicket: true }] }, + form: { create: { isRequired: true, fields: { create: [ + { type: 'paragraph', label: 'About you', order: 0 }, + { type: 'text', label: 'Emergency contact', isRequired: true, order: 1 }, + ] } } }, + }, + include: { eventOptions: true }, + }); + const pastEvent = await prisma.event.create({ + data: { + title: 'E2E Last Sunday', description: 'It ended yesterday.', startDate: at(-1, 7), endDate: at(-1, 10), + price: 0, isHidden: true, createdById: users.supervisor.id, + eventOptions: { create: [{ name: 'Entry', price: 0, isMainTicket: true }] }, + }, + include: { eventOptions: true }, + }); + const latecomer = await mk('user', 'Lerato Late', 'late@e2e.test', '0820000009'); + const lateReg = await prisma.registration.create({ + data: { + userId: latecomer.id, eventId: pastEvent.id, status: 'paid', + registrationOptions: { create: [{ eventOptionId: pastEvent.eventOptions[0].id, quantity: 2, priceSnapshot: 0, tranches: { create: [{ quantity: 2, priceSnapshot: 0 }] } }] }, + }, + }); + await generateTicketsForRegistration(lateReg.id); + const out = { users: Object.fromEntries(Object.entries(users).map(([k, u]) => [k, { id: u.id, name: u.name, email: u.email, token: generateToken(u.id, u.role, u.tokenVersion || 0) }])), - events: { free: free.id, paid: paid.id, course: course.id, dropIn: dropIn.id, conference: conference.id, kids: kids.id, serving: serving.id }, + events: { free: free.id, paid: paid.id, course: course.id, dropIn: dropIn.id, conference: conference.id, kids: kids.id, serving: serving.id, form: formEvent.id, past: pastEvent.id }, campuses: { north: { id: north.id, slug: north.slug }, south: { id: south.id, slug: south.slug } }, northTicketQr: northTicket.qrCode, + formOptionId: formEvent.eventOptions[0].id, course: { sessions: course.sessions.map(s => ({ id: s.id, label: s.label })), ticketId: ticket.id, qrCode: ticket.qrCode }, // An account that has never answered the news question (asked once after login). newsPromptUser: await (async () => { diff --git a/apps/events/frontend/package-lock.json b/apps/events/frontend/package-lock.json index b505e04..3849399 100644 --- a/apps/events/frontend/package-lock.json +++ b/apps/events/frontend/package-lock.json @@ -1,12 +1,12 @@ { "name": "hope-events-frontend", - "version": "1.51.17", + "version": "1.52.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "hope-events-frontend", - "version": "1.51.17", + "version": "1.52.1", "dependencies": { "@dnd-kit/core": "^6.3.1", "@hookform/resolvers": "^5.2.1", diff --git a/apps/events/frontend/package.json b/apps/events/frontend/package.json index e2a975f..ce23b1b 100644 --- a/apps/events/frontend/package.json +++ b/apps/events/frontend/package.json @@ -1,6 +1,6 @@ { "name": "hope-events-frontend", - "version": "1.51.17", + "version": "1.52.1", "private": true, "scripts": { "dev": "next dev", diff --git a/apps/events/frontend/src/app/dashboard/admin/audit-log/page.tsx b/apps/events/frontend/src/app/dashboard/admin/audit-log/page.tsx index 492b645..eff96bd 100644 --- a/apps/events/frontend/src/app/dashboard/admin/audit-log/page.tsx +++ b/apps/events/frontend/src/app/dashboard/admin/audit-log/page.tsx @@ -80,6 +80,10 @@ const ACTION_LABELS: Record = { registrations_bulk: "Bulk action on registrations", attendance_marked: "Attendance marked", attendance_unmarked: "Attendance unmarked", + attendee_form_waived: "Attendee form left for later", + tickets_issued_override: "Tickets issued by an admin (correction)", + registration_complimentary: "Balance made complimentary", + checkin_corrected: "Check-in corrected after the fact", certificate_issued: "Certificate issued", certificate_revoked: "Certificate revoked", event_sessions_changed: "Event sessions changed", diff --git a/apps/events/frontend/src/app/dashboard/admin/corrections/page.tsx b/apps/events/frontend/src/app/dashboard/admin/corrections/page.tsx new file mode 100644 index 0000000..816706a --- /dev/null +++ b/apps/events/frontend/src/app/dashboard/admin/corrections/page.tsx @@ -0,0 +1,408 @@ +"use client"; + +import React, { Suspense, useCallback, useEffect, useMemo, useState } from "react"; +import { useRouter, useSearchParams } from "next/navigation"; +import { Wrench, AlertTriangle, CheckCircle2, Ticket, FileText } from "lucide-react"; +import { useAuth } from "@/hooks/useAuth"; +import { useDismissingState } from "@/hooks/useDismissingState"; +import { fetchEvent, fetchManagedEvents } from "@/lib/api"; +import { apiV2Data } from "@/lib/apiV2"; +import { errorMessage } from "@/lib/utils"; +import { BackLink } from "@/components/shared/BackLink"; +import { EventPicker } from "@/components/shared/EventPicker"; +import { AttendeeFormModal, type AttendeeFormDef } from "@/components/shared/AttendeeFormModal"; +import type { Event } from "@/types"; + +// GET /api/v2/corrections/events/{id} (services/corrections.ts) +type CorrectionTicket = { + id: string; qrCode: string; label: string; isMainTicket: boolean; name: string; quantity: number; + sessionIds: string[]; checkedIn: Record; +}; +type CorrectionRow = { + id: string; status: string; createdAt: string; + user: { id: string; name: string; email: string | null; phoneNumber: string | null }; + totalDue: number; paid: number; balance: number; places: number; ticketPlaces: number; + missingTickets: boolean; formsNeeded: number; formWaived: boolean; ticketsReleased: boolean; complimentary: number; + tickets: CorrectionTicket[]; +}; +type CorrectionEvent = { id: string; title: string; startDate: string; endDate: string; closed: boolean; formRequired: boolean; sessions: { id: string; label: string; startsAt: string }[] }; +type Filter = "attention" | "unpaid" | "not_checked_in" | "all"; + +const WHOLE_EVENT = "event"; +const rand = (n: number) => `R ${(n || 0).toFixed(2)}`; +const notCheckedIn = (r: CorrectionRow) => r.tickets.some(t => t.isMainTicket && t.sessionIds.some(s => (t.checkedIn[s] || 0) < t.quantity)); +const needsAttention = (r: CorrectionRow) => r.missingTickets || r.formsNeeded > 0 || (r.balance > 0 && r.tickets.length === 0); + +/** One registration: what's wrong with it, and the fixes. */ +function RegistrationCard({ row, event, form, token, onChanged, onMessage }: { + row: CorrectionRow; event: CorrectionEvent; form: AttendeeFormDef; token: string; + onChanged: () => void; onMessage: (ok: boolean, text: string) => void; +}) { + const [action, setAction] = useState<"none" | "tickets" | "free">("none"); + const [skipForm, setSkipForm] = useState(row.formsNeeded > 0); + const [send, setSend] = useState(false); + const [reason, setReason] = useState(""); + const [busy, setBusy] = useState(false); + const [showForm, setShowForm] = useState(false); + const unpaid = row.status !== "paid" && !row.ticketsReleased; + + const run = async () => { + setBusy(true); + try { + if (action === "free") { + const res = await (apiV2Data("post", "/corrections/registrations/{id}/complimentary", { + params: { id: row.id }, authToken: token, body: { skipForm, send, reason: reason || null }, + }) as Promise<{ amount: number; ticketsIssued: number }>); + onMessage(true, `${row.user.name}: ${rand(res.amount)} made complimentary${res.ticketsIssued ? ` — ${res.ticketsIssued} ticket(s) issued` : ""}.`); + } else { + const res = await (apiV2Data("post", "/corrections/registrations/{id}/tickets", { + params: { id: row.id }, authToken: token, body: { skipForm, payLater: unpaid, send, reason: reason || null }, + }) as Promise<{ ticketsIssued: number }>); + onMessage(true, `${row.user.name}: ${res.ticketsIssued ? `${res.ticketsIssued} ticket(s) issued` : "tickets are up to date"}${unpaid ? " — the balance is still owed" : ""}.`); + } + setAction("none"); + setReason(""); + onChanged(); + } catch (e) { + onMessage(false, errorMessage(e) || "That didn't work."); + } finally { + setBusy(false); + } + }; + + const chips: { text: string; tone: string }[] = []; + if (row.missingTickets) chips.push({ text: `Missing tickets (${row.ticketPlaces} of ${row.places})`, tone: "bg-red-50 text-red-700" }); + if (row.formsNeeded > 0) chips.push({ text: `${row.formsNeeded} form${row.formsNeeded === 1 ? "" : "s"} to fill in`, tone: "bg-amber-50 text-amber-700" }); + if (row.balance > 0) chips.push({ text: `Owes ${rand(row.balance)}`, tone: "bg-orange-50 text-orange-700" }); + if (row.formWaived) chips.push({ text: "Form left for later", tone: "bg-gray-100 text-gray-600" }); + if (row.ticketsReleased) chips.push({ text: "Tickets issued before payment", tone: "bg-blue-50 text-blue-700" }); + if (row.complimentary > 0) chips.push({ text: `Complimentary ${rand(row.complimentary)}`, tone: "bg-emerald-50 text-emerald-700" }); + + return ( +

+
+
+
{row.user.name || "Guest"}
+
{[row.user.email, row.user.phoneNumber].filter(Boolean).join(" · ") || "No contact details"}
+
+
+
{row.status.replace("_", " ")} · {rand(row.paid)} of {rand(row.totalDue)}
+
#{row.id.slice(0, 8)}
+
+
+ + {chips.length > 0 && ( +
+ {chips.map(c => {c.text})} +
+ )} + +
+ {row.formsNeeded > 0 && ( + + )} + {(row.missingTickets || unpaid || row.formsNeeded > 0) && ( + + )} + {row.balance > 0 && !event.closed && ( + + )} +
+ + {action !== "none" && ( +
+

+ {action === "free" + ? `${rand(row.balance)} is written off as a complimentary discount — income stays ${rand(row.paid)} — and the registration is marked paid.` + : unpaid + ? `The tickets are issued now. ${rand(row.balance)} is still owed and shows as outstanding until it's paid.` + : "Issues the tickets this registration is missing."} +

+ {row.formsNeeded > 0 && ( + + )} + + +
+ + +
+
+ )} + + {row.tickets.length > 0 && ( +
+ {row.tickets.map(t => )} +
+ )} + + {showForm && ( + { + setShowForm(false); + onMessage(true, `${row.user.name}: ${later ? "form left for later" : "form saved"}${ticketsIssued ? ` — ${ticketsIssued} ticket(s) issued` : ""}.`); + onChanged(); + }} + /> + )} +
+ ); +} + +/** A ticket's check-ins per session, with check in / undo whatever the time. */ +function TicketCheckIn({ ticket, event, token, onChanged, onMessage }: { + ticket: CorrectionTicket; event: CorrectionEvent; token: string; + onChanged: () => void; onMessage: (ok: boolean, text: string) => void; +}) { + const [busyKey, setBusyKey] = useState(null); + const label = (key: string) => key === WHOLE_EVENT ? "Checked in" : (event.sessions.find(s => s.id === key)?.label || "Session"); + + const change = async (key: string, present: boolean) => { + setBusyKey(key); + try { + await apiV2Data("post", "/corrections/tickets/{id}/check-in", { + params: { id: ticket.id }, authToken: token, + body: { sessionId: key === WHOLE_EVENT ? null : key, present }, + }); + onMessage(true, `${ticket.name}: ${present ? "checked in" : "check-in undone"}${key === WHOLE_EVENT ? "" : ` for ${label(key)}`}.`); + onChanged(); + } catch (e) { + onMessage(false, errorMessage(e) || "That didn't work."); + } finally { + setBusyKey(null); + } + }; + + return ( +
+
+ {ticket.label}{ticket.quantity > 1 ? ` ×${ticket.quantity}` : ""} + {ticket.name} +
+
+ {ticket.sessionIds.map(key => { + const n = ticket.checkedIn[key] || 0; + const full = n >= ticket.quantity; + return ( + + {full ? : null} + {label(key)}: {n}/{ticket.quantity} + {!full && ( + + )} + {n > 0 && ( + + )} + + ); + })} +
+
+ ); +} + +function CorrectionsContent() { + const { user, token, loading } = useAuth(); + const router = useRouter(); + const search = useSearchParams(); + const [events, setEvents] = useState([]); + const [eventId, setEventId] = useState(search.get("event") || ""); + // Kept with the event they're for, so changing events never shows the last one's. + const [loaded, setLoaded] = useState<{ event: CorrectionEvent; registrations: CorrectionRow[] } | null>(null); + const [formOf, setFormOf] = useState<{ eventId: string; form: AttendeeFormDef } | null>(null); + const data = loaded && loaded.event.id === eventId ? loaded : null; + const form = formOf?.eventId === eventId ? formOf.form : null; + const [busy, setBusy] = useState(false); + const [filter, setFilter] = useState("attention"); + const [query, setQuery] = useState(""); + const [sendMissing, setSendMissing] = useState(false); + const [message, setMessage] = useDismissingState<{ ok: boolean; text: string } | null>(null); + const isAdmin = user?.role === "admin"; + + useEffect(() => { + if (loading) return; + if (!user) router.replace("/login"); + }, [user, loading, router]); + + // Every event — past and closed ones too, newest first. + useEffect(() => { + if (!token || !isAdmin) return; + fetchManagedEvents(token, { past: true, inactive: true }) + .then(evs => setEvents([...(evs || [])].sort((a, b) => new Date(b.startDate).getTime() - new Date(a.startDate).getTime()))) + .catch(() => setEvents([])); + }, [token, isAdmin]); + + const load = useCallback(async () => { + if (!token || !eventId) return; + try { + setLoaded(await (apiV2Data("get", "/corrections/events/{id}", { params: { id: eventId }, authToken: token }) as Promise<{ event: CorrectionEvent; registrations: CorrectionRow[] }>)); + } catch (e) { + setMessage({ ok: false, text: errorMessage(e) || "Couldn't load the event." }); + } + }, [token, eventId, setMessage]); + + useEffect(() => { load(); }, [load]); + useEffect(() => { + if (!eventId) return; + fetchEvent(eventId, { authToken: token || undefined }) + .then(ev => setFormOf({ eventId, form: ev?.form })) + .catch(() => setFormOf({ eventId, form: null })); + }, [eventId, token]); + + const rows = useMemo(() => { + const q = query.trim().toLowerCase(); + return (data?.registrations || []).filter(r => { + if (filter === "attention" && !needsAttention(r)) return false; + if (filter === "unpaid" && !(r.balance > 0)) return false; + if (filter === "not_checked_in" && !notCheckedIn(r)) return false; + if (!q) return true; + return [r.user.name, r.user.email, r.user.phoneNumber, r.id].some(v => String(v || "").toLowerCase().includes(q)); + }); + }, [data, filter, query]); + + const counts = useMemo(() => { + const regs = data?.registrations || []; + return { + attention: regs.filter(needsAttention).length, + unpaid: regs.filter(r => r.balance > 0).length, + not_checked_in: regs.filter(notCheckedIn).length, + all: regs.length, + missing: regs.filter(r => r.missingTickets).length, + }; + }, [data]); + + const issueMissing = async () => { + if (!token || !eventId) return; + setBusy(true); + try { + const res = await (apiV2Data("post", "/corrections/events/{id}/issue-missing", { params: { id: eventId }, authToken: token, body: { send: sendMissing } }) as Promise<{ registrations: number; tickets: number; failed: { name: string; message: string }[] }>); + setMessage({ + ok: res.failed.length === 0, + text: `${res.tickets} ticket(s) issued for ${res.registrations} registration(s).${res.failed.length ? ` Not fixed: ${res.failed.map(f => `${f.name} (${f.message})`).join("; ")}` : ""}`, + }); + await load(); + } catch (e) { + setMessage({ ok: false, text: errorMessage(e) || "That didn't work." }); + } finally { + setBusy(false); + } + }; + + const onMessage = useCallback((ok: boolean, text: string) => setMessage({ ok, text }), [setMessage]); + + if (!loading && user && !isAdmin) { + return
Corrections are for admins only.
; + } + + const FILTERS: { key: Filter; label: string }[] = [ + { key: "attention", label: "Needs attention" }, + { key: "unpaid", label: "Owes money" }, + { key: "not_checked_in", label: "Not checked in" }, + { key: "all", label: "All" }, + ]; + + return ( +
+
+
+ +
+
+ +

Corrections

+
+
+

+ Put registrations right after the fact: issue tickets held back by an attendee form or still unpaid, make a balance free, and check people in after the event. Everything is kept in the audit log. +

+ + { setEventId(id); setFilter("attention"); }} placeholder="Choose an event (past events too)" /> + + {message && ( +
{message.text}
+ )} + + {data && ( + <> +
+ {data.event.closed && Closed (cashed up) — money can’t change; tickets and check-ins can} + {data.event.formRequired && Required attendee form} + {new Date(data.event.endDate) < new Date() && Event is over} +
+ + {counts.missing > 0 && ( +
+
+ +
+ {counts.missing} paid registration{counts.missing === 1 ? " is" : "s are"} missing tickets. Issue them all now — attendee forms still outstanding are left for later. +
+
+
+ + +
+
+ )} + +
+ {FILTERS.map(f => ( + + ))} + setQuery(e.target.value)} aria-label="Search registrations" /> +
+ +
+ {rows.map(r => ( + + ))} + {rows.length === 0 && ( +
+ {filter === "attention" ? "Nothing needs putting right at this event." : "No registrations match."} +
+ )} +
+ + )} +
+ ); +} + +export default function CorrectionsPage() { + return ( + + + + ); +} diff --git a/apps/events/frontend/src/app/dashboard/admin/page.tsx b/apps/events/frontend/src/app/dashboard/admin/page.tsx index ea8c0b9..f2f9e11 100644 --- a/apps/events/frontend/src/app/dashboard/admin/page.tsx +++ b/apps/events/frontend/src/app/dashboard/admin/page.tsx @@ -8,7 +8,7 @@ import { useVisiblePolling } from "@/hooks/useVisiblePolling"; import { Calendar, Banknote, Gift, Users, Ticket, QrCode, ClipboardList, UserPlus, FileText, MessageCircle, BarChart2, Mail, Wallet, DoorOpen, History, TicketPercent, ShieldCheck, ListChecks, WifiOff, BedDouble, Filter, ClipboardCheck, Inbox, - Baby, HandHeart, Layers, + Baby, HandHeart, Layers, Wrench, } from "lucide-react"; import { StatCard, StatCardRow } from "@/components/shared/StatCard"; import { QuickActionTile, QuickActionGrid } from "@/components/shared/QuickActionTile"; @@ -48,6 +48,7 @@ const QUICK_ACTIONS = [ { href: "/dashboard/admin/forms", label: "Attendee forms", description: "View submitted attendee forms", icon: FileText }, { href: "/dashboard/supervisor/email-attendees", label: "Email attendees", description: "Send a message to attendees of an event", icon: Mail }, { href: "/dashboard/supervisor/whatsapp-attendees", label: "WhatsApp attendees", description: "Send a WhatsApp message to event attendees", icon: MessageCircle }, + { href: "/dashboard/admin/corrections", label: "Corrections", description: "Missing tickets, free tickets, forms and late check-ins", icon: Wrench }, { href: "/dashboard/admin/cashup", label: "Post-event Cashup", description: "Set costs, reconcile takings, and close out events", icon: Wallet }, { href: "/dashboard/admin/audit-log", label: "Audit log", description: "Review refunds, manual registrations, event and settings changes", icon: History }, { href: "/dashboard/admin/data-requests", label: "Data requests", description: "POPIA: people asking to correct or delete their information", icon: Inbox }, diff --git a/apps/events/frontend/src/app/dashboard/staff/kids/page.tsx b/apps/events/frontend/src/app/dashboard/staff/kids/page.tsx index 97f9f41..22c43b6 100644 --- a/apps/events/frontend/src/app/dashboard/staff/kids/page.tsx +++ b/apps/events/frontend/src/app/dashboard/staff/kids/page.tsx @@ -312,7 +312,7 @@ export default function KidsDeskPage() { const r = await (apiV2Data("post", "/events/{id}/kids/check-out", { params: { id: eventId }, authToken: token, - body: { code: lookup.code, checkInIds: ids, collectedBy, sessionId: sessionId || undefined }, + body: { code: lookup.code ?? "", checkInIds: ids, collectedBy, sessionId: sessionId || undefined }, }) as Promise<{ checkedOut: { name: string }[] }>); setMsg({ type: "ok", text: `Collected: ${r.checkedOut.map(c => c.name).join(", ")}.` }); setLookup(null); diff --git a/apps/events/frontend/src/app/dashboard/supervisor/at-the-door/page.tsx b/apps/events/frontend/src/app/dashboard/supervisor/at-the-door/page.tsx index 8d38312..5e4b3ba 100644 --- a/apps/events/frontend/src/app/dashboard/supervisor/at-the-door/page.tsx +++ b/apps/events/frontend/src/app/dashboard/supervisor/at-the-door/page.tsx @@ -19,6 +19,7 @@ import { bookableSessions, choosesSessions, isPickOption, todaysSession } from " import { SessionPicker } from "@/components/events/SessionPicker"; import type { Event, EventOption, PublicBundle, Registration, Ticket as TicketRecord, UserSummary } from "@/types"; import { EventPicker } from "@/components/shared/EventPicker"; +import { AttendeeFormModal, formsStillNeeded } from "@/components/shared/AttendeeFormModal"; import { apiV2, apiV2Data } from "@/lib/apiV2"; type NewAttendee = { name: string; email: string | null; phone: string | null; notifPref: "email" | "whatsapp" | "both" }; @@ -198,12 +199,37 @@ export default function AtTheDoorPage() { const [info, setInfo] = useDismissingState(null); const [error, setError] = useDismissingState(null); + // A required attendee form holds the tickets back: it pops up to fill in now, or "Fill in + // later" (tickets are issued anyway and the attendee gets a link). + const [formPrompt, setFormPrompt] = useState<{ registration: Registration; needed: number } | null>(null); + const loadFull = (id: string) => apiV2Data("get", "/registrations/{id}/full", { params: { id }, authToken: token }) as Promise; + const promptFormFor = (full: Registration) => { + const needed = formsStillNeeded(doorEvent?.form, full); + if (needed > 0 && full.status !== "cancelled") setFormPrompt({ registration: full, needed }); + return needed; + }; + const handleRegistrationCreated = (registration: Registration) => { setActiveRegistration(registration); // 🚀 Jump automatically (see effect below) + if ((registration.formsNeeded || 0) > 0) setFormPrompt({ registration, needed: registration.formsNeeded || 0 }); }; const handleRegistrationSelected = (registration: Registration) => { setActiveRegistration(registration); + // The search list doesn't carry the forms, so look at the whole registration. + loadFull(registration.id).then(promptFormFor).catch(() => {}); + }; + + const handleFormDone = async ({ later, ticketsIssued, sentTo }: { later: boolean; ticketsIssued: number; sentTo?: string[] }) => { + const reg = formPrompt?.registration; + setFormPrompt(null); + const issued = ticketsIssued > 0 ? " Tickets issued." : ""; + setInfo(later + ? `Form left for later${sentTo && sentTo.length ? ` — a link was sent by ${sentTo.join(" and ")}` : ""}.${issued}` + : `Attendee form saved.${issued}`); + if (reg) { + try { setActiveRegistration(await loadFull(reg.id)); } catch {} + } }; useEffect(() => { @@ -404,9 +430,14 @@ export default function AtTheDoorPage() { // Tickets are generated and emailed/WhatsApped automatically server-side // once a registration reaches "paid" (see paymentController) — no need to // fetch/print them here, just move straight to checking the attendee in. + // Unless a required attendee form holds them back: that pops up first. setActiveRegistration(reg); - setInfo("Payment recorded — tickets sent. Ready to check in."); setMode("checkin"); + if (reg && promptFormFor(reg) > 0) { + setInfo("Payment recorded — fill in the attendee form (or choose Fill in later) to issue the tickets."); + return; + } + setInfo("Payment recorded — tickets sent. Ready to check in."); }; const handleDonation = (user?: UserSummary) => { @@ -499,7 +530,12 @@ export default function AtTheDoorPage() { )} {mode === "checkin" && ( - + loadFull(activeRegistration.id).then(full => { + if (promptFormFor(full) === 0) setError("No attendee form is outstanding. If the tickets are still missing, an admin can issue them in Corrections."); + }).catch(e => setError(errorMessage(e) || "Couldn't load the registration")) : undefined} + /> )} {mode === "tickets" && ( @@ -550,6 +586,17 @@ export default function AtTheDoorPage() { seed={newAttendeeSeed} onConfirm={handleNewAttendeeConfirm} /> + {formPrompt && ( + + )} ); } @@ -1027,12 +1074,14 @@ function DoorTicketsPanel({ token, eventId }: { token: string | null; eventId: s ); } -function DoorCheckInPanel({ token, eventId, registration, setError, setInfo }: { +function DoorCheckInPanel({ token, eventId, registration, setError, setInfo, onFillForm }: { token: string | null; eventId: string; registration: Registration | null; setError: (e: string | null) => void; setInfo: (s: string | null) => void; + /** No tickets yet: open the attendee form that holds them back. */ + onFillForm?: () => void; }) { const [ticketsForEvent, setTicketsForEvent] = useState([]); const [loading, setLoading] = useState(false); @@ -1053,7 +1102,8 @@ function DoorCheckInPanel({ token, eventId, registration, setError, setInfo }: { } }, [token, eventId]); - useEffect(() => { load(); }, [load]); + // Again when the registration changes: its tickets may have just been issued. + useEffect(() => { load(); }, [load, registration]); if (!registration) { return ( @@ -1117,9 +1167,18 @@ function DoorCheckInPanel({ token, eventId, registration, setError, setInfo }: { )} {!loading && myTickets.length === 0 && ( -
- No Main Tickets on this registration -
+ registration.status === "paid" && onFillForm ? ( +
+ No tickets yet. If the event has an attendee form, it’s holding them back. + +
+ ) : ( +
+ {registration.status === "paid" ? "No Main Tickets on this registration" : "No tickets yet — they're issued once it's paid."} +
+ ) )}
diff --git a/apps/events/frontend/src/app/dashboard/supervisor/manual-registration/page.tsx b/apps/events/frontend/src/app/dashboard/supervisor/manual-registration/page.tsx index 30b50a2..f834564 100644 --- a/apps/events/frontend/src/app/dashboard/supervisor/manual-registration/page.tsx +++ b/apps/events/frontend/src/app/dashboard/supervisor/manual-registration/page.tsx @@ -167,6 +167,21 @@ function AttendeeFormsSection({ registration, form, formsData, setFormsData }: { } }; + // The tickets stop waiting for the form (issued now if it's paid); the attendee gets a link. + const later = async () => { + if (!token) return; + try { + setSubmitting(true); + setError(null); setInfo(null); + const res = await (apiV2Data("post", "/registrations/{id}/form-later", { params: { id: registration.id }, authToken: token, body: {} }) as Promise<{ ticketsIssued: number; sentTo: string[] }>); + setInfo(`Form left for later${res?.sentTo?.length ? ` — a link was sent by ${res.sentTo.join(' and ')}` : ''}.${res?.ticketsIssued ? ' Tickets issued.' : ''}`); + } catch (e) { + setError(errorMessage(e) || 'Failed to leave the form for later'); + } finally { + setSubmitting(false); + } + }; + if (!form || !Array.isArray(form.fields) || count === 0) return null; return (
@@ -212,7 +227,10 @@ function AttendeeFormsSection({ registration, form, formsData, setFormsData }: {
))}
- +
+ + {form.isRequired && } +
); } diff --git a/apps/events/frontend/src/app/dashboard/supervisor/manual/page.tsx b/apps/events/frontend/src/app/dashboard/supervisor/manual/page.tsx index 77549ae..d9125d2 100644 --- a/apps/events/frontend/src/app/dashboard/supervisor/manual/page.tsx +++ b/apps/events/frontend/src/app/dashboard/supervisor/manual/page.tsx @@ -18,6 +18,7 @@ import type { Event, EventOption, PublicBundle, Registration, RegistrationOption import { BackLink } from "@/components/shared/BackLink"; import { EventPicker } from "@/components/shared/EventPicker"; import { apiV2Data } from "@/lib/apiV2"; +import { AttendeeFormModal, type AttendeeFormDef } from "@/components/shared/AttendeeFormModal"; // ─── Pricing helpers ───────────────────────────────────────────────────────── @@ -91,6 +92,15 @@ export default function ManualRegistrationPage() { const [paySubmitting, setPaySubmitting] = useState(false); const [payMessage, setPayMessage] = useDismissingState(null); const [payError, setPayError] = useDismissingState(null); + // A required attendee form holding the tickets back: fill it in now, or "Fill in later". + const [formPrompt, setFormPrompt] = useState<{ registrationId: string; needed: number; form: AttendeeFormDef; name?: string } | null>(null); + const promptForm = async (registrationId: string, needed: number, eventId: string, name?: string) => { + if (!(needed > 0)) return; + try { + const ev = await fetchEvent(eventId, { authToken: token || undefined }); + setFormPrompt({ registrationId, needed, form: ev?.form, name }); + } catch {} + }; // Load all users for client-side fuzzy matching useEffect(() => { @@ -164,7 +174,7 @@ export default function ManualRegistrationPage() { if (!payRegistrationId) { setPayError("Please select a registration"); return; } try { setPaySubmitting(true); - await apiV2Data("post", "/payments", { + const paid = await (apiV2Data("post", "/payments", { authToken: token, body: { amount: amt, @@ -174,8 +184,11 @@ export default function ManualRegistrationPage() { isDonation: false, paidAt: payPaidAtLocal ? new Date(payPaidAtLocal).toISOString() : undefined, }, - }); - setPayMessage(`Payment recorded (R ${amt.toFixed(2)}).`); + }) as Promise<{ formsNeeded?: number; registration?: { eventId?: string } }>); + setPayMessage(`Payment recorded (R ${amt.toFixed(2)}).${(paid?.formsNeeded || 0) > 0 ? " The attendee form is holding the tickets back." : ""}`); + const paidReg = allRegistrations.find(r => r.id === payRegistrationId); + const paidEventId = paid?.registration?.eventId || paidReg?.eventId; + if (paidEventId) promptForm(payRegistrationId, paid?.formsNeeded || 0, paidEventId, paidReg?.user?.name); setPayAmount(""); setPayPaidAtLocal(""); // Refresh registrations so the displayed outstanding balance updates @@ -362,6 +375,7 @@ export default function ManualRegistrationPage() { setMessage(res?.couponError ? `Manual registration created, but the code wasn't applied: ${res.couponError}` : coupon ? `Manual registration created with code ${coupon.code}.` : "Manual registration created successfully."); + if ((res?.formsNeeded || 0) > 0) setFormPrompt({ registrationId: res.id, needed: res.formsNeeded || 0, form: fullEvent?.form, name: res.user?.name || guest.name }); // Pre-load the Record Payment tab with this registration so it's ready to go the // moment a supervisor clicks over — the tab itself is never switched to automatically. @@ -771,6 +785,24 @@ export default function ManualRegistrationPage() { )} + {formPrompt && ( + { + setFormPrompt(null); + const issued = ticketsIssued > 0 ? " Tickets issued." : ""; + const text = later + ? `Attendee form left for later${sentTo && sentTo.length ? ` — a link was sent by ${sentTo.join(" and ")}` : ""}.${issued}` + : `Attendee form saved.${issued}`; + if (tab === "payment") setPayMessage(text); else setMessage(text); + }} + /> + )} ); } diff --git a/apps/events/frontend/src/app/dashboard/user/page.tsx b/apps/events/frontend/src/app/dashboard/user/page.tsx index 896bb77..9ae4c44 100644 --- a/apps/events/frontend/src/app/dashboard/user/page.tsx +++ b/apps/events/frontend/src/app/dashboard/user/page.tsx @@ -1033,11 +1033,14 @@ export default function UserDashboardPage() { {renderGroup('Early bird', earlyBirdRows)} {renderGroup('Standard price', standardRows)} - {Number(activeReg.discountTotal || 0) - Number(activeReg.bundleDiscount || 0) > 0.005 && ( + {Number(activeReg.discountTotal || 0) - Number(activeReg.bundleDiscount || 0) - Number(activeReg.complimentaryDiscount || 0) > 0.005 && (
- Discount code{activeCoupon?.coupon?.code ? <> {activeCoupon.coupon.code} : null} — −{formatRand(Number(activeReg.discountTotal) - Number(activeReg.bundleDiscount || 0))} + Discount code{activeCoupon?.coupon?.code ? <> {activeCoupon.coupon.code} : null} — −{formatRand(Number(activeReg.discountTotal) - Number(activeReg.bundleDiscount || 0) - Number(activeReg.complimentaryDiscount || 0))}
)} + {Number(activeReg.complimentaryDiscount || 0) > 0.005 && ( +
Complimentary — −{formatRand(Number(activeReg.complimentaryDiscount))}
+ )} {canModifyActive && activeBill && activeBill.outstanding > 0 && !activeCoupon && (
diff --git a/apps/events/frontend/src/app/self-service/page.tsx b/apps/events/frontend/src/app/self-service/page.tsx index 3061d4c..c75379f 100644 --- a/apps/events/frontend/src/app/self-service/page.tsx +++ b/apps/events/frontend/src/app/self-service/page.tsx @@ -197,6 +197,9 @@ export default function SelfServicePage() { // ── Event form (attendee form) state ──────────────────────────── const [currentRegistrationId, setCurrentRegistrationId] = useState(null); const [currentTicketIndex, setCurrentTicketIndex] = useState(0); + // Attendee forms the server says this registration still needs (it counts places already + // on an existing registration, and a picked-session booking once). + const [formsToFill, setFormsToFill] = useState(0); const [allFormAnswers, setAllFormAnswers] = useState[]>([]); const [currentTicketAnswers, setCurrentTicketAnswers] = useState>({}); const [formSubmitLoading, setFormSubmitLoading] = useState(false); @@ -264,16 +267,24 @@ export default function SelfServicePage() { }), [quantities]); const bundleQuote = useBundleQuote({ eventId: selectedEventId || "", basket: kioskBasket, token: supervisorToken, forUserId: matchedAccount?.id ?? null }); - // Does the selected event have a required form? + // Does the selected event have a required form? (Statements and headings aren't questions.) const eventHasRequiredForm = useMemo(() => { - return !!(selectedEvent?.form?.isRequired && (selectedEvent.form.fields || []).some(f => f.type !== 'statement')); + return !!(selectedEvent?.form?.isRequired && (selectedEvent.form.fields || []).some(f => f.type !== 'statement' && f.type !== 'paragraph')); }, [selectedEvent]); - // Answerable form fields (exclude statement-type display fields) + // Answerable form fields (exclude statement and heading display fields) const answerableFields = useMemo(() => { if (!selectedEvent?.form) return []; return (selectedEvent.form.fields || []) - .filter(f => f.type !== 'statement') + .filter(f => f.type !== 'statement' && f.type !== 'paragraph') + .sort((a, b) => (a.order || 0) - (b.order || 0)); + }, [selectedEvent]); + + // Statements and headings, shown above the questions + const formTexts = useMemo(() => { + if (!selectedEvent?.form) return []; + return (selectedEvent.form.fields || []) + .filter(f => f.type === 'statement' || f.type === 'paragraph') .sort((a, b) => (a.order || 0) - (b.order || 0)); }, [selectedEvent]); @@ -486,11 +497,13 @@ export default function SelfServicePage() { }) as Promise); setCurrentRegistrationId(result?.id || null); + const needed = result?.formsNeeded ?? (eventHasRequiredForm ? mainTicketCount : 0); + setFormsToFill(needed); setRegistrationIsFree(result?.status === "paid" || (result?.totalDueComputed ?? total) === 0); setConfirmationName(visitorName.trim()); - // If event has a required form and there are main tickets, show form step - if (eventHasRequiredForm && mainTicketCount > 0 && result?.id) { + // If the required form still holds the tickets back, show the form step + if (needed > 0 && result?.id) { setCurrentTicketIndex(0); setAllFormAnswers([]); setCurrentTicketAnswers({}); @@ -528,7 +541,7 @@ export default function SelfServicePage() { const collectedAnswers = [...allFormAnswers, currentTicketAnswers]; // If more tickets remain, advance to the next one - if (currentTicketIndex < mainTicketCount - 1) { + if (currentTicketIndex < formsToFill - 1) { setAllFormAnswers(collectedAnswers); setCurrentTicketAnswers({}); setCurrentTicketIndex((i) => i + 1); @@ -606,6 +619,7 @@ export default function SelfServicePage() { setFormError(null); setCurrentRegistrationId(null); setCurrentTicketIndex(0); + setFormsToFill(0); setAllFormAnswers([]); setCurrentTicketAnswers({}); setFormSubmitError(null); @@ -1219,13 +1233,13 @@ export default function SelfServicePage() {

{selectedEvent.title}

Attendee Information

- {mainTicketCount > 1 && ( + {formsToFill > 1 && (

- Attendee {currentTicketIndex + 1} of {mainTicketCount} + Attendee {currentTicketIndex + 1} of {formsToFill}

- {Array.from({ length: mainTicketCount }).map((_, i) => ( + {Array.from({ length: formsToFill }).map((_, i) => (
)} - {mainTicketCount <= 1 && ( + {formsToFill <= 1 && (

This form is required to complete your registration.

)}
+ {formTexts.map((field) => ( +
+ {field.label} + {field.helpText &&

{field.helpText}

} +
+ ))} {answerableFields.map((field) => (