Add sponsor a spot

Events can allow sponsorships: a "Sponsor a spot" button lets anyone
(guests included) pay through Yoco for whole spots or a custom amount,
anonymously or with a name and message. Payments land as event
donations in a sponsorship pool that supervisors assign with the
existing donation flow. Adds optional public progress towards a goal,
a sponsor receipt and Automations thank-you, pool columns in the
Donations report, and sponsorship labels/filter in Payments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-19 15:04:29 +02:00
co-authored by Claude Opus 5.5
parent 9bdd3250bf
commit dff83d47af
23 changed files with 594 additions and 177 deletions
@@ -24,7 +24,7 @@ async function scheduleAutomations(req, res) {
html: j.html ? String(j.html) : undefined,
text: (!j.html && j.text) ? String(j.text) : (j.text ? String(j.text) : undefined),
template: 'custom',
filter: { status: undefined, attendeeIds: undefined },
filter: { status: undefined, attendeeIds: undefined, ...(j.audience === 'sponsors' ? { audience: 'sponsors' } : {}) },
};
if (j.promoEventId && typeof j.promoEventId === 'string') {
payload.promoEventId = j.promoEventId;
@@ -44,7 +44,7 @@ function toAbsoluteUrl(req, url) {
// @access Private/Admin
const createEvent = async (req, res) => {
try {
const { title, description, startDate, endDate, registrationDeadline, goLiveAt, price, picture, redirectUrl, isHidden, requiresAuth, requiresRegistration, allowNamedAttendees, requiresParentalConsent, consentText, consentCollectMedical, consentCollectEmergency, consentCollectPhoto, waitlistEnabled, waitlistOfferHours, waitlistPartialOffers, allowTicketTransfer, collectGender, contactName, contactPhone, contactEmail, location } = req.body;
const { title, description, startDate, endDate, registrationDeadline, goLiveAt, price, picture, redirectUrl, isHidden, requiresAuth, requiresRegistration, allowNamedAttendees, requiresParentalConsent, consentText, consentCollectMedical, consentCollectEmergency, consentCollectPhoto, waitlistEnabled, waitlistOfferHours, waitlistPartialOffers, allowTicketTransfer, collectGender, allowSponsorships, sponsorshipGoalSpots, showSponsorshipProgress, contactName, contactPhone, contactEmail, location } = req.body;
const data = {
id: uuidv4(),
@@ -72,6 +72,9 @@ const createEvent = async (req, res) => {
waitlistEnabled: waitlistEnabled === true,
allowTicketTransfer: allowTicketTransfer !== false,
collectGender: collectGender === true,
allowSponsorships: allowSponsorships === true,
sponsorshipGoalSpots: sponsorshipGoalSpots ? Math.max(1, parseInt(sponsorshipGoalSpots, 10) || 0) || null : null,
showSponsorshipProgress: showSponsorshipProgress !== false,
waitlistOfferHours: Math.min(168, Math.max(1, parseInt(waitlistOfferHours, 10) || 24)),
waitlistPartialOffers: waitlistPartialOffers !== false,
contactName: contactName || null,
@@ -538,7 +541,7 @@ const updateEvent = async (req, res) => {
ip: getClientIp(req),
});
const { title, description, startDate, endDate, registrationDeadline, goLiveAt, price, picture, isActive, redirectUrl, isHidden, requiresAuth, requiresRegistration, allowNamedAttendees, requiresParentalConsent, consentText, consentCollectMedical, consentCollectEmergency, consentCollectPhoto, waitlistEnabled, waitlistOfferHours, waitlistPartialOffers, allowTicketTransfer, collectGender, contactName, contactPhone, contactEmail, location } = req.body;
const { title, description, startDate, endDate, registrationDeadline, goLiveAt, price, picture, isActive, redirectUrl, isHidden, requiresAuth, requiresRegistration, allowNamedAttendees, requiresParentalConsent, consentText, consentCollectMedical, consentCollectEmergency, consentCollectPhoto, waitlistEnabled, waitlistOfferHours, waitlistPartialOffers, allowTicketTransfer, collectGender, allowSponsorships, sponsorshipGoalSpots, showSponsorshipProgress, contactName, contactPhone, contactEmail, location } = req.body;
const data = {
title: title || event.title,
@@ -563,6 +566,9 @@ const updateEvent = async (req, res) => {
waitlistEnabled: waitlistEnabled !== undefined ? waitlistEnabled === true : event.waitlistEnabled,
allowTicketTransfer: allowTicketTransfer !== undefined ? allowTicketTransfer !== false : event.allowTicketTransfer,
collectGender: collectGender !== undefined ? collectGender === true : event.collectGender,
allowSponsorships: allowSponsorships !== undefined ? allowSponsorships === true : event.allowSponsorships,
sponsorshipGoalSpots: sponsorshipGoalSpots !== undefined ? (sponsorshipGoalSpots ? Math.max(1, parseInt(sponsorshipGoalSpots, 10) || 0) || null : null) : event.sponsorshipGoalSpots,
showSponsorshipProgress: showSponsorshipProgress !== undefined ? showSponsorshipProgress !== false : event.showSponsorshipProgress,
waitlistOfferHours: waitlistOfferHours !== undefined ? Math.min(168, Math.max(1, parseInt(waitlistOfferHours, 10) || 24)) : event.waitlistOfferHours,
waitlistPartialOffers: waitlistPartialOffers !== undefined ? waitlistPartialOffers !== false : event.waitlistPartialOffers,
// Editing the consent text starts a new version; parents who already agreed keep
@@ -1388,6 +1394,24 @@ const emailEventAttendees = async (req, res) => {
}
const recipients = Array.from(uniqMap.values());
// Sponsors of this event instead of its attendees (e.g. the post-event thank-you).
if (filter?.audience === 'sponsors') {
recipients.length = 0;
registrations.length = 0;
const sponsorships = await prisma.payment.findMany({
where: { eventId, isDonation: true, isSponsorship: true, amount: { gt: 0 } },
include: { user: { select: { name: true, email: true, isActive: true } } },
orderBy: { createdAt: 'asc' },
});
const seen = new Set();
for (const s of sponsorships) {
const email = (s.user?.email || '').trim();
if (!email || email.endsWith('@guest.local') || email.endsWith('@deleted.invalid') || seen.has(email)) continue;
seen.add(email);
recipients.push({ email, name: s.sponsorName || s.user?.name || '' });
}
}
if (dryRun) {
return res.json({ eventId, matched: recipients.length, recipients: recipients.slice(0, 20) });
}
@@ -0,0 +1,112 @@
const axios = require('axios');
const prisma = require('../config/db');
const { safeErrorMessage } = require('../utils/errorUtils');
const { sponsorshipError, spotPrice, sponsorshipCharge, poolSummary } = require('../utils/sponsorship');
const fail = (res, error) => res.status(error.statusCode || error.response?.status || 400).json({ message: safeErrorMessage(error) });
async function sponsorableEvent(eventId) {
const event = await prisma.event.findUnique({ where: { id: String(eventId || '') }, include: { eventOptions: { select: { isMainTicket: true, price: true } } } });
if (!event || !event.isActive) throw sponsorshipError('Event not found', 404);
if (!event.allowSponsorships) throw sponsorshipError('This event isn’t taking sponsorships.');
if (event.cashupStatus === 'closed' || new Date(event.endDate) < new Date()) throw sponsorshipError('This event has ended and is no longer taking sponsorships.');
return event;
}
async function poolFor(event) {
const sponsorships = await prisma.payment.findMany({ where: { eventId: event.id, isDonation: true, isSponsorship: true, amount: { gt: 0 } }, select: { id: true, amount: true } });
const legs = sponsorships.length
? await prisma.payment.findMany({ where: { originalPaymentId: { in: sponsorships.map(s => s.id) }, isDonation: false }, select: { originalPaymentId: true, amount: true } })
: [];
return poolSummary(sponsorships, legs, spotPrice(event));
}
// @desc Public sponsorship progress for an event (never names who was helped)
// @route GET /api/sponsorships/event/:eventId
// @access Public
const getEventSponsorship = async (req, res) => {
try {
const event = await prisma.event.findUnique({ where: { id: req.params.eventId }, include: { eventOptions: { select: { isMainTicket: true, price: true } } } });
if (!event || !event.isActive || !event.allowSponsorships) return res.json({ enabled: false });
const pool = await poolFor(event);
const open = event.cashupStatus !== 'closed' && new Date(event.endDate) >= new Date();
res.json({
enabled: true,
open,
spotPrice: spotPrice(event),
showProgress: event.showSponsorshipProgress,
goalSpots: event.sponsorshipGoalSpots,
spotsFunded: event.showSponsorshipProgress ? pool.spotsFunded : null,
sponsors: event.showSponsorshipProgress ? pool.sponsors : null,
});
} catch (error) {
fail(res, error);
}
};
// @desc Start a Yoco checkout to sponsor spots (or a custom amount) at an event
// @route POST /api/sponsorships/checkout { eventId, spots? | amount?, anonymous?, sponsorName?, message?, name?, email?, phone? }
// @access Public (guests give a name and email for the receipt)
const createSponsorCheckout = async (req, res) => {
try {
const { eventId, spots, amount, anonymous, sponsorName, message, name, email, phone } = req.body || {};
const event = await sponsorableEvent(eventId);
const charge = sponsorshipCharge({ spots, amount }, spotPrice(event));
let payer = req.user || null;
if (!payer) {
const { hasValidEmail, findOrCreateAccount } = require('../utils/accountMatch');
const cleanName = String(name || '').trim().slice(0, 100);
if (!cleanName) throw sponsorshipError('Enter your name.');
if (!hasValidEmail(email)) throw sponsorshipError('Enter your email address so we can send your receipt.');
// An existing account is reused; otherwise a quiet inactive one holds the receipt —
// no activation link is sent, since a sponsor doesn't need to log in.
payer = (await findOrCreateAccount({ name: cleanName, email: String(email).trim(), phone })).user;
}
const isAnonymous = anonymous === true;
const displayName = isAnonymous ? null : (String(sponsorName || '').trim() || payer.name || '').slice(0, 100) || null;
const note = String(message || '').trim().slice(0, 300) || null;
const base = (process.env.FRONTEND_URL || process.env.APP_BASE_URL || 'http://localhost:3001').replace(/\/$/, '');
const back = `${base}/events/${encodeURIComponent(event.id)}`;
const amountInCents = Math.round(charge.amount * 100);
const label = charge.spots ? `Sponsor ${charge.spots} spot${charge.spots > 1 ? 's' : ''} at ${event.title}` : `Sponsorship for ${event.title}`;
const checkoutData = {
amount: amountInCents,
currency: 'ZAR',
metadata: {
type: 'sponsorship', isDonation: true, eventId: event.id, eventTitle: event.title, userId: payer.id,
sponsorAnonymous: isAnonymous ? 'true' : 'false',
...(displayName ? { sponsorName: displayName } : {}),
...(note ? { sponsorMessage: note } : {}),
...(charge.spots ? { spots: String(charge.spots) } : {}),
},
successUrl: `${back}?sponsored=1`,
cancelUrl: back,
failureUrl: `${back}?sponsored=failed`,
lineItems: [{ displayName: label, quantity: 1, pricingDetails: { price: amountInCents } }],
};
const response = await axios.post('https://payments.yoco.com/api/checkouts', checkoutData, {
headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${process.env.YOCO_SECRET_KEY}`, 'Idempotency-Key': `spon_${event.id}_${payer.id}_${amountInCents}_${Date.now()}` },
});
res.json({ redirectUrl: response.data.redirectUrl, checkoutId: response.data.id, amount: charge.amount });
} catch (error) {
if (error.response) console.error('Sponsor checkout error:', error.response.data || error.message);
fail(res, error);
}
};
// @desc The sponsorship pool for an event (supervisors)
// @route GET /api/sponsorships/event/:eventId/pool
// @access Private/Supervisor
const getPool = async (req, res) => {
try {
const event = await prisma.event.findUnique({ where: { id: req.params.eventId }, include: { eventOptions: { select: { isMainTicket: true, price: true } } } });
if (!event) throw sponsorshipError('Event not found', 404);
res.json({ eventId: event.id, spotPrice: spotPrice(event), goalSpots: event.sponsorshipGoalSpots, ...(await poolFor(event)) });
} catch (error) {
fail(res, error);
}
};
module.exports = { getEventSponsorship, createSponsorCheckout, getPool, poolFor };
@@ -325,7 +325,13 @@ const handlePaymentSucceeded = async (webhookData) => {
userId: resolvedUserId,
recordedById: resolvedUserId, // self-service webhook payment — payer is the recorder
eventId: registration?.eventId || metadata?.eventId || null,
isDonation: !registration?.id
isDonation: !registration?.id,
...(!registration?.id && metadata?.type === 'sponsorship' ? {
isSponsorship: true,
sponsorAnonymous: String(metadata.sponsorAnonymous) === 'true',
sponsorName: String(metadata.sponsorAnonymous) === 'true' ? null : (metadata.sponsorName ? String(metadata.sponsorName).slice(0, 100) : null),
sponsorMessage: metadata.sponsorMessage ? String(metadata.sponsorMessage).slice(0, 300) : null,
} : {})
},
include: {
user: {
+9
View File
@@ -180,6 +180,7 @@ app.use('/api/consent', require('./routes/consentRoutes'));
app.use('/api/waitlist', require('./routes/waitlistRoutes'));
app.use('/api/scan-locks', require('./routes/scanLockRoutes'));
app.use('/api/allocations', require('./routes/allocationRoutes'));
app.use('/api/sponsorships', require('./routes/sponsorshipRoutes'));
app.use('/api/backups', backupRoutes);
// Pre-warm the settings cache so synchronous helpers have DB values from startup
@@ -636,6 +637,14 @@ app.get('/docs', async (req, res) => {
]},
]},
{ title: 'Sponsor a spot', base: '/api/sponsorships', endpoints: [
{ method:'GET', path:'/api/sponsorships/event/:eventId', auth:'Public', desc:'Sponsorship progress for an event (spots funded, goal) — never who was helped',
responses:[{ status:200, desc:'Progress', body:{ enabled:true, open:true, spotPrice:450, showProgress:true, goalSpots:20, spotsFunded:12, sponsors:9 }}]},
{ method:'POST', path:'/api/sponsorships/checkout', auth:'Public (optional login)', desc:'Start a Yoco checkout to sponsor spots or a custom amount; the money lands in the event sponsorship pool',
request:{ body:{ eventId:'ev-uuid-...', spots:2, anonymous:false, sponsorName:'The Smith family', message:'Have a great camp!', name:'Sam Smith', email:'sam@example.com' }},
responses:[{ status:200, desc:'Checkout created', body:{ redirectUrl:'https://pay.yoco.com/...', amount:900 }}]},
{ method:'GET', path:'/api/sponsorships/event/:eventId/pool', auth:'supervisor+', desc:'Sponsorship pool totals: received, assigned, remaining' },
]},
{ title: 'Rooms & groups', base: '/api/allocations', endpoints: [
{ method:'GET', path:'/api/allocations/event/:eventId', auth:'supervisor+', desc:'Allocation board: sets with groups and assignments, named attendees, possible leaders' },
{ method:'POST', path:'/api/allocations/sets', auth:'supervisor+', desc:'Create an allocation set', request:{ body:{ eventId:'ev-uuid-...', name:'Rooms', showOnTicket:true }}},
@@ -0,0 +1,10 @@
const express = require('express');
const router = express.Router();
const { getEventSponsorship, createSponsorCheckout, getPool } = require('../controllers/sponsorshipController');
const { protect, supervisor, optionalAuth } = require('../middleware/authMiddleware');
router.get('/event/:eventId', getEventSponsorship);
router.get('/event/:eventId/pool', protect, supervisor, getPool);
router.post('/checkout', optionalAuth, createSponsorCheckout);
module.exports = router;
@@ -533,7 +533,7 @@ function buildPaymentReceipt(payment) {
}
// Donation receipt
const subject = `Donation received – ${eventTitle}`;
const subject = payment.isSponsorship ? `Thank you for sponsoring a spot – ${eventTitle}` : `Donation received – ${eventTitle}`;
const preheader = `Thank you for your donation of ${fmtAmount(payment.amount)} to ${eventTitle}.`;
const body = `
<p style="font-size:22px;font-weight:800;color:#0f172a;margin:0 0 8px 0;letter-spacing:-0.3px">Thank you for your donation!</p>
@@ -541,7 +541,7 @@ function buildPaymentReceipt(payment) {
<p style="margin:0 0 4px 0;color:#374151;font-family:${ff}">Hi <strong>${payment.user?.name || 'there'}</strong>,</p>
<p style="margin:0 0 28px 0;color:#374151;font-family:${ff}">
We received your donation of <strong>${fmtAmount(payment.amount)}</strong> to <strong>${eventTitle}</strong>. Your support means the world to us.
We received your donation of <strong>${fmtAmount(payment.amount)}</strong> to <strong>${eventTitle}</strong>. Your support means the world to us.${payment.isSponsorship ? ' It goes into the sponsorship pool and helps someone attend who otherwise couldn’t.' : ''}
</p>
${callout(`<strong style="font-size:15px">${fmtAmount(payment.amount)} donated</strong><br/>
@@ -0,0 +1,72 @@
/**
* Sponsor a spot — public donations into an event's bursary pool.
*
* A sponsorship is an ordinary event donation (isDonation) also flagged isSponsorship,
* so supervisors hand it out with the existing assign/unassign-donation flow. These
* helpers are pure: what one spot costs, what a sponsor is charged, and the pool totals.
*/
const { computeDonationRemaining } = require('./donationUtils');
const MIN_AMOUNT = 15; // Yoco's minimum charge, same as other donations
const MAX_SPOTS = 100;
const MAX_AMOUNT = 100000;
function sponsorshipError(message, statusCode = 400) {
const err = new Error(message);
err.statusCode = statusCode;
return err;
}
/** The price of one spot: the cheapest paid main ticket (or the event price), or null if free. */
function spotPrice(event) {
const prices = (event.eventOptions || [])
.filter(o => o.isMainTicket && Number(o.price) > 0)
.map(o => Number(o.price));
if (prices.length) return Math.min(...prices);
return Number(event.price) > 0 ? Number(event.price) : null;
}
/**
* What the sponsor pays: `spots` whole spots, or a custom `amount`.
* @returns {{ amount: number, spots: number|null }}
*/
function sponsorshipCharge({ spots, amount }, price) {
if (spots !== undefined && spots !== null && spots !== '') {
const n = Number(spots);
if (!Number.isInteger(n) || n < 1 || n > MAX_SPOTS) throw sponsorshipError(`Choose between 1 and ${MAX_SPOTS} spots.`);
if (!price) throw sponsorshipError('This event has no ticket price — enter an amount instead.');
return { amount: Math.round(n * price * 100) / 100, spots: n };
}
const a = Math.round(Number(amount) * 100) / 100;
if (!Number.isFinite(a) || a <= 0) throw sponsorshipError('Enter an amount, or choose a number of spots.');
if (a < MIN_AMOUNT) throw sponsorshipError(`The minimum is R${MIN_AMOUNT}.`);
if (a > MAX_AMOUNT) throw sponsorshipError(`For gifts over R${MAX_AMOUNT.toLocaleString('en-ZA')}, please contact us directly.`);
return { amount: a, spots: null };
}
/**
* Pool totals for an event.
* @param {Array} sponsorships - sponsorship donation payments [{ id, amount }]
* @param {Array} legs - payments with originalPaymentId set (assignments, refunds)
* @param {number|null} price - one spot
*/
function poolSummary(sponsorships, legs, price) {
const legsBy = new Map();
for (const l of legs || []) legsBy.set(l.originalPaymentId, [...(legsBy.get(l.originalPaymentId) || []), l]);
let received = 0, remaining = 0;
for (const s of sponsorships || []) {
received += Number(s.amount) || 0;
remaining += Math.max(0, computeDonationRemaining(s.amount, legsBy.get(s.id) || []));
}
const round = (n) => Math.round(n * 100) / 100;
return {
received: round(received),
assigned: round(received - remaining),
remaining: round(remaining),
sponsors: (sponsorships || []).length,
spotsFunded: price ? Math.floor((received + 0.001) / price) : null,
};
}
module.exports = { MIN_AMOUNT, MAX_SPOTS, sponsorshipError, spotPrice, sponsorshipCharge, poolSummary };