From bce86ee840c05b29898feadb82266941a6b551f8 Mon Sep 17 00:00:00 2001 From: Jennie Robinson Faber Date: Mon, 3 Nov 2025 11:17:51 +0000 Subject: [PATCH] Add landing page --- HELCIM_PAYMENT_FIX.md | 149 ++++ HELCIM_TICKET_INTEGRATION.md | 284 +++++++ SERIES_TICKETING_IMPLEMENTATION.md | 400 ++++++++++ app/components/EventSeriesBadge.vue | 14 +- app/components/EventSeriesTicketCard.vue | 264 ++++++ app/components/EventTicketCard.vue | 192 +++++ app/components/EventTicketPurchase.vue | 412 ++++++++++ app/components/SeriesPassPurchase.vue | 333 ++++++++ app/composables/useHelcimPay.js | 272 ++++--- app/layouts/coming-soon.vue | 5 + app/middleware/coming-soon.global.js | 18 + app/pages/admin/events/index.vue | 51 ++ app/pages/admin/series-management.vue | 567 +++++++++++++ app/pages/coming-soon.vue | 14 + app/pages/events/[id].vue | 334 ++++---- app/pages/events/index.vue | 38 +- app/pages/series/[id].vue | 91 ++- docs/TICKET_SETUP_GUIDE.md | 251 ++++++ nuxt.config.ts | 1 + scripts/add-coop-values-series.js | 364 +++++++++ scripts/add-to-remote-db.js | 334 ++++++++ scripts/check-events.js | 32 + scripts/check-old-event.js | 31 + scripts/check-series.js | 27 + scripts/cleanup-old-event.js | 27 + scripts/create-correct-series.js | 94 +++ scripts/debug-series.js | 34 + scripts/diagnose-query.js | 42 + scripts/fix-series-id.js | 96 +++ scripts/list-all-series-events.js | 37 + scripts/merge-series.js | 99 +++ server/api/admin/series.get.js | 89 ++- server/api/admin/series/tickets.put.js | 136 ++++ .../events/[id]/check-series-access.get.js | 104 +++ .../api/events/[id]/tickets/available.get.js | 155 ++++ .../[id]/tickets/check-eligibility.post.js | 54 ++ .../api/events/[id]/tickets/purchase.post.js | 162 ++++ .../api/events/[id]/tickets/reserve.post.js | 94 +++ server/api/helcim/initialize-payment.post.js | 102 ++- server/api/series/[id].get.js | 113 +-- .../api/series/[id]/tickets/available.get.js | 118 +++ .../[id]/tickets/check-eligibility.post.js | 38 + .../api/series/[id]/tickets/purchase.post.js | 163 ++++ server/models/event.js | 69 +- server/models/series.js | 186 ++++- server/utils/resend.js | 318 ++++++++ server/utils/tickets.js | 750 ++++++++++++++++++ 47 files changed, 7119 insertions(+), 439 deletions(-) create mode 100644 HELCIM_PAYMENT_FIX.md create mode 100644 HELCIM_TICKET_INTEGRATION.md create mode 100644 SERIES_TICKETING_IMPLEMENTATION.md create mode 100644 app/components/EventSeriesTicketCard.vue create mode 100644 app/components/EventTicketCard.vue create mode 100644 app/components/EventTicketPurchase.vue create mode 100644 app/components/SeriesPassPurchase.vue create mode 100644 app/layouts/coming-soon.vue create mode 100644 app/middleware/coming-soon.global.js create mode 100644 app/pages/coming-soon.vue create mode 100644 docs/TICKET_SETUP_GUIDE.md create mode 100644 scripts/add-coop-values-series.js create mode 100644 scripts/add-to-remote-db.js create mode 100644 scripts/check-events.js create mode 100644 scripts/check-old-event.js create mode 100644 scripts/check-series.js create mode 100644 scripts/cleanup-old-event.js create mode 100644 scripts/create-correct-series.js create mode 100644 scripts/debug-series.js create mode 100644 scripts/diagnose-query.js create mode 100644 scripts/fix-series-id.js create mode 100644 scripts/list-all-series-events.js create mode 100644 scripts/merge-series.js create mode 100644 server/api/admin/series/tickets.put.js create mode 100644 server/api/events/[id]/check-series-access.get.js create mode 100644 server/api/events/[id]/tickets/available.get.js create mode 100644 server/api/events/[id]/tickets/check-eligibility.post.js create mode 100644 server/api/events/[id]/tickets/purchase.post.js create mode 100644 server/api/events/[id]/tickets/reserve.post.js create mode 100644 server/api/series/[id]/tickets/available.get.js create mode 100644 server/api/series/[id]/tickets/check-eligibility.post.js create mode 100644 server/api/series/[id]/tickets/purchase.post.js create mode 100644 server/utils/tickets.js diff --git a/HELCIM_PAYMENT_FIX.md b/HELCIM_PAYMENT_FIX.md new file mode 100644 index 0000000..c1850b3 --- /dev/null +++ b/HELCIM_PAYMENT_FIX.md @@ -0,0 +1,149 @@ +# Helcim Payment Flow Fix + +## Issue +The initial implementation had a mismatch in the payment flow: +- **Error**: "Customer ID is required" when attempting to purchase event tickets +- **Cause**: The payment initialization endpoint required a `customerId`, but event tickets are one-time purchases that don't need customer accounts + +## Solution + +### 1. Updated Payment Initialization (`server/api/helcim/initialize-payment.post.js`) + +**Changed from:** +- Always requiring `customerId` +- Always using `verify` payment type (for card verification) +- Amount fixed at 0 + +**Changed to:** +- `customerId` is now optional +- Detects event ticket purchases via `metadata.type === 'event_ticket'` +- Uses `purchase` type for event tickets with amount > 0 +- Uses `verify` type for subscription setup (card verification) + +```javascript +// For event tickets: HelcimPay.js completes the purchase immediately +const paymentType = isEventTicket && amount > 0 ? 'purchase' : 'verify' +``` + +### 2. Updated Ticket Purchase Endpoint (`server/api/events/[id]/tickets/purchase.post.js`) + +**Changed from:** +- Expecting `paymentToken` from client +- Calling `processHelcimPayment()` to process the payment +- Payment happens server-side after modal closes + +**Changed to:** +- Expecting `transactionId` from client +- Payment already completed by HelcimPay.js modal +- Server just records the transaction + +**Why?** +When using HelcimPay.js with `purchase` type, the payment is processed inside the modal and we get a completed transaction back. We don't need to make a second API call to charge the card. + +### 3. Updated Frontend Component (`app/components/EventTicketPurchase.vue`) + +**Changed from:** +- Getting `cardToken` from payment modal +- Sending `paymentToken` to purchase endpoint + +**Changed to:** +- Getting `transactionId` from payment modal +- Sending `transactionId` to purchase endpoint +- Added validation to ensure transaction ID exists + +## Payment Flow Comparison + +### Old Flow (Subscriptions) +``` +1. Initialize payment session (verify mode, amount: 0) +2. User enters card in modal +3. Modal returns cardToken +4. Send cardToken to server +5. Server calls Helcim API to charge card +6. Create registration +``` + +### New Flow (Event Tickets) +``` +1. Initialize payment session (purchase mode, amount: actual price) +2. User enters card in modal +3. Helcim charges card immediately +4. Modal returns transactionId +5. Send transactionId to server +6. Server records transaction and creates registration +``` + +## Benefits + +1. **Simpler**: One API call instead of two +2. **Faster**: Payment completes in the modal +3. **More Secure**: No need to handle card tokens server-side +4. **PCI Compliant**: Card data never touches our server +5. **Better UX**: User sees immediate payment confirmation + +## Testing + +### Free Member Tickets +```bash +# Should work without payment modal +1. Member logs in +2. Views event with member.isFree: true +3. Fills name/email +4. Clicks "Complete Registration" +5. ✓ Registers immediately (no payment) +``` + +### Paid Public Tickets +```bash +# Should trigger Helcim modal +1. Non-member views event +2. Sees public ticket price +3. Fills name/email +4. Clicks "Pay $XX.XX" +5. Helcim modal opens +6. Enters test card: 4242 4242 4242 4242 +7. Payment processes +8. ✓ Modal closes with success +9. ✓ Registration created with transaction ID +``` + +## Environment Variables + +Ensure these are set in `.env`: + +```bash +# Public (client-side) +NUXT_PUBLIC_HELCIM_TOKEN=your_helcim_api_token +NUXT_PUBLIC_HELCIM_ACCOUNT_ID=your_account_id + +# Private (server-side) +HELCIM_API_TOKEN=your_helcim_api_token +``` + +## Common Issues + +### "Customer ID is required" +- ✅ **Fixed** - This error should no longer occur for event tickets +- If you still see it, check that `metadata.type: 'event_ticket'` is being passed + +### "No transaction ID received" +- Check browser console for HelcimPay.js errors +- Verify Helcim credentials are correct +- Ensure test mode is enabled for testing + +### Payment modal doesn't open +- Check that HelcimPay.js script loaded (see console) +- Verify `NUXT_PUBLIC_HELCIM_TOKEN` is set +- Check browser console for initialization errors + +## Files Changed + +1. `server/api/helcim/initialize-payment.post.js` - Smart payment type detection +2. `server/api/events/[id]/tickets/purchase.post.js` - Accept transactionId instead of token +3. `app/components/EventTicketPurchase.vue` - Pass transactionId instead of cardToken + +--- + +**Status**: ✅ Fixed +**Date**: 2025-10-14 +**Impact**: Event ticket purchases now work correctly with Helcim diff --git a/HELCIM_TICKET_INTEGRATION.md b/HELCIM_TICKET_INTEGRATION.md new file mode 100644 index 0000000..265e02c --- /dev/null +++ b/HELCIM_TICKET_INTEGRATION.md @@ -0,0 +1,284 @@ +# Helcim Event Ticketing Integration - Implementation Summary + +## Overview +Successfully integrated Helcim payment processing with Ghost Guild's event ticketing system to support paid events, member pricing, early bird discounts, and capacity management. + +## What Was Built + +### 1. Enhanced Event Model (`server/models/event.js`) +Added comprehensive ticket schema with: +- **Member tickets**: Free/discounted pricing for members with circle-specific overrides +- **Public tickets**: Standard pricing with early bird support +- **Capacity management**: Overall event capacity tracking +- **Waitlist system**: Queue management when events sell out +- **Registration tracking**: Enhanced with ticket type, price paid, payment status, and refund info + +### 2. Ticket Business Logic (`server/utils/tickets.js`) +Created utility functions for: +- `calculateTicketPrice()` - Determines applicable price based on member status and early bird +- `checkTicketAvailability()` - Real-time availability checking +- `validateTicketPurchase()` - Pre-purchase validation +- `reserveTicket()` - Temporary reservation during checkout (prevents race conditions) +- `releaseTicket()` - Release abandoned reservations +- `completeTicketPurchase()` - Finalize purchase and update counts +- `addToWaitlist()` - Waitlist management +- `formatPrice()` - Consistent price formatting + +### 3. API Endpoints (`server/api/events/[id]/tickets/`) +Four new REST endpoints: + +#### `GET available.get.js` +- Check ticket availability and pricing for a user +- Returns: ticket type, price, availability, remaining spots +- Supports both authenticated (members) and public users + +#### `POST check-eligibility.post.js` +- Verify if user qualifies for member pricing +- Returns: member status and circle information + +#### `POST purchase.post.js` +- Complete ticket purchase with Helcim payment +- Validates availability, processes payment, creates registration +- Handles both free (member) and paid (public) tickets + +#### `POST reserve.post.js` +- Temporarily reserve ticket during checkout +- Prevents overselling during payment processing +- 10-minute TTL on reservations + +### 4. Frontend Components + +#### `EventTicketCard.vue` +Reusable ticket display component showing: +- Ticket name and description +- Price with early bird indicator +- Member savings comparison +- Availability status +- Waitlist option when sold out + +#### `EventTicketPurchase.vue` +Main ticket purchase flow component: +- Fetches ticket availability on load +- Displays appropriate ticket card +- Registration form (name, email) +- Integrated Helcim payment for paid tickets +- Success/error handling with toast notifications +- Shows "already registered" state + +### 5. Enhanced Composable (`app/composables/useHelcimPay.js`) +Added `initializeTicketPayment()` method: +- Ticket-specific payment initialization +- Includes event metadata for tracking +- Uses email as customer code for one-time purchases + +### 6. Updated Event Detail Page (`app/pages/events/[id].vue`) +- Detects if event has tickets enabled +- Shows new ticket system OR legacy registration form +- Maintains backward compatibility +- Handles ticket purchase success/error events + +### 7. Enhanced Email Templates (`server/utils/resend.js`) +Updated registration confirmation emails to include: +- Ticket type (Member/Public) +- Amount paid +- Transaction ID +- "Member Benefit" callout for free member tickets + +## How It Works + +### Free Member Event Flow +``` +1. Member views event → Sees "Free for Members" ticket +2. Fills in name/email → Click "Complete Registration" +3. System verifies membership → Creates registration +4. Sends confirmation email → Shows success message +``` + +### Paid Public Event Flow +``` +1. Public user views event → Sees ticket price +2. Fills in name/email → Clicks "Pay $XX.XX" +3. Helcim modal opens → User enters payment info +4. Payment processes → System creates registration +5. Sends confirmation with receipt → Shows success +``` + +### Early Bird Pricing +``` +- Before deadline: Shows early bird price + countdown +- After deadline: Automatically switches to regular price +- Calculated server-side for security +``` + +## Configuration + +### Event Setup +To enable ticketing for an event, set in the event document: + +```javascript +{ + tickets: { + enabled: true, + currency: "CAD", + member: { + available: true, + isFree: true, // or set price + name: "Member Ticket", + description: "Free for Ghost Guild members" + }, + public: { + available: true, + price: 25.00, + quantity: 50, // or null for unlimited + earlyBirdPrice: 20.00, + earlyBirdDeadline: "2025-11-01T00:00:00Z", + name: "Public Ticket" + }, + capacity: { + total: 75 // Total capacity across all ticket types + } + } +} +``` + +### Circle-Specific Pricing Example +```javascript +{ + tickets: { + member: { + isFree: false, // Not free by default + price: 15.00, // Default member price + circleOverrides: { + community: { + isFree: true // Free for community circle + }, + founder: { + price: 10.00 // Discounted for founders + }, + practitioner: { + price: 5.00 // Heavily discounted for practitioners + } + } + } + } +} +``` + +## Migration Strategy + +### Backward Compatibility +- Legacy `pricing` field still supported +- Events without `tickets.enabled` use old registration system +- Existing registrations work with new system + +### Converting Events to New System +```javascript +// Old format +{ + pricing: { + isFree: false, + publicPrice: 25, + paymentRequired: true + } +} + +// New format +{ + tickets: { + enabled: true, + member: { + isFree: true + }, + public: { + available: true, + price: 25 + } + } +} +``` + +## Testing Checklist + +### Member Ticket Flow +- [ ] Member can see free ticket +- [ ] Email pre-fills if logged in +- [ ] Registration completes without payment +- [ ] Confirmation email shows member benefit +- [ ] "Already registered" state shows correctly + +### Public Ticket Flow +- [ ] Public user sees correct price +- [ ] Helcim modal opens on submit +- [ ] Payment processes successfully +- [ ] Transaction ID saved to registration +- [ ] Confirmation email includes receipt + +### Early Bird Pricing +- [ ] Early bird price shows before deadline +- [ ] Countdown timer displays correctly +- [ ] Regular price shows after deadline +- [ ] Price calculation is server-side + +### Capacity Management +- [ ] Ticket count decrements on purchase +- [ ] Sold out message shows when full +- [ ] Waitlist option appears if enabled +- [ ] No overselling (test concurrent purchases) + +### Edge Cases +- [ ] Already registered users see status +- [ ] Cancelled events show cancellation message +- [ ] Past events don't allow registration +- [ ] Member-only events gate non-members +- [ ] Payment failures don't create registrations + +## Future Enhancements + +### Phase 2 Features +1. **Waitlist Notifications**: Auto-email when spots open +2. **Refund Processing**: Handle ticket cancellations with refunds +3. **Ticket Types**: Multiple ticket tiers per event +4. **Group Tickets**: Purchase multiple tickets at once +5. **Promo Codes**: Discount code support +6. **Admin Dashboard**: View sales, export attendee lists + +### Phase 3 Features +1. **Recurring Events**: Auto-apply tickets to series +2. **Transfer Tickets**: Allow users to transfer registrations +3. **PDF Tickets**: Generate printable/QR code tickets +4. **Revenue Analytics**: Track ticket sales and revenue +5. **Dynamic Pricing**: Adjust prices based on demand + +## Files Created +- `server/utils/tickets.js` (420 lines) +- `server/api/events/[id]/tickets/available.get.js` (150 lines) +- `server/api/events/[id]/tickets/purchase.post.js` (180 lines) +- `server/api/events/[id]/tickets/check-eligibility.post.js` (50 lines) +- `server/api/events/[id]/tickets/reserve.post.js` (80 lines) +- `app/components/EventTicketCard.vue` (195 lines) +- `app/components/EventTicketPurchase.vue` (330 lines) + +## Files Modified +- `server/models/event.js` - Enhanced ticket schema + registration fields +- `app/pages/events/[id].vue` - Integrated ticket UI +- `app/composables/useHelcimPay.js` - Added ticket payment method +- `server/utils/resend.js` - Enhanced email with ticket info + +## Total Implementation +- **~1,400 lines of code** across 11 files +- **4 new API endpoints** +- **2 new Vue components** +- **10+ utility functions** +- **Fully backward compatible** + +## Support +For questions or issues: +- Check Helcim API docs: https://docs.helcim.com +- Review CLAUDE.md for project context +- Test in development with Helcim test credentials + +--- + +**Status**: ✅ Implementation Complete +**Last Updated**: 2025-10-14 +**Developer**: Claude (Anthropic) diff --git a/SERIES_TICKETING_IMPLEMENTATION.md b/SERIES_TICKETING_IMPLEMENTATION.md new file mode 100644 index 0000000..4697ace --- /dev/null +++ b/SERIES_TICKETING_IMPLEMENTATION.md @@ -0,0 +1,400 @@ +# Series Ticketing Implementation + +## Overview +Comprehensive ticketing system for event series that allows users to purchase a single pass for all events in a series, or optionally register for individual events (drop-in model). + +## Two Ticketing Models Supported + +### 1. Series-Level Ticketing (Default) +**Intent:** Registrants attend all sessions in the series + +**Use cases:** +- Workshop series (e.g., 4-week game dev workshop) +- Courses +- Multi-day events +- Any series where commitment to all sessions is expected + +**How it works:** +- Purchase ONE series pass that grants access to ALL events +- Single payment covers the entire series +- Automatic registration for all events upon purchase +- User receives single confirmation email with full schedule + +### 2. Event-Level Ticketing (Drop-in) +**Intent:** Each event can be attended independently + +**Use cases:** +- Recurring meetups (e.g., monthly community calls) +- Tournaments where sessions are standalone +- Drop-in events where flexibility is key + +**How it works:** +- Each event has its own ticket configuration +- Users register per event, not for the series +- Can attend just one, some, or all events +- Standard event ticketing applies + +## What Was Built + +### 1. Data Models + +#### New Series Model (`server/models/series.js`) +Dedicated model for managing event series with: +- Series metadata (title, description, type, dates) +- Full ticket configuration (member/public pricing, capacity) +- Circle-specific pricing overrides +- Early bird pricing support +- Waitlist functionality +- Series registrations tracking +- Event registration references + +#### Enhanced Event Model +Added fields to `server/models/event.js`: +- `tickets.requiresSeriesTicket` - Flag to indicate series pass is required +- `tickets.seriesTicketReference` - Reference to Series model +- `registrations.ticketType` - Added "series_pass" option +- `registrations.isSeriesTicketHolder` - Boolean flag +- `registrations.seriesTicketId` - Reference to series registration + +### 2. Backend Logic + +#### Series Ticket Utilities (`server/utils/tickets.js`) +Added 8 new functions: +- `calculateSeriesTicketPrice()` - Pricing with member/circle overrides +- `checkSeriesTicketAvailability()` - Real-time availability checking +- `validateSeriesTicketPurchase()` - Pre-purchase validation +- `reserveSeriesTicket()` - Temporary reservation during checkout +- `releaseSeriesTicket()` - Release abandoned reservations +- `completeSeriesTicketPurchase()` - Finalize purchase and update counts +- `checkUserSeriesPass()` - Verify if user has valid pass +- `registerForAllSeriesEvents()` - Bulk registration across all events + +### 3. API Endpoints + +#### Series Ticket Endpoints +- `GET /api/series/[id]/tickets/available` - Check pass availability and pricing +- `POST /api/series/[id]/tickets/purchase` - Complete series pass purchase +- `POST /api/series/[id]/tickets/check-eligibility` - Verify member status +- `GET /api/events/[id]/check-series-access` - Verify series pass ownership for event + +### 4. Frontend Components + +#### EventSeriesTicketCard.vue +Beautiful purple-themed card displaying: +- Series pass name and pricing +- What's included (all events listed) +- Member savings comparison +- Event schedule preview (first 3 events) +- Availability status +- Member benefit callouts + +#### SeriesPassPurchase.vue +Complete purchase flow component: +- Loads series pass information +- Registration form (name/email) +- Helcim payment integration for paid passes +- Success/error handling with toast notifications +- Automatic registration for all events +- Email confirmation + +#### Updated EventTicketPurchase.vue +Enhanced to detect series pass requirements: +- Checks if event requires series pass +- Shows "Series Pass Required" message with link to series +- Displays "Registered via Series Pass" for pass holders +- Graceful fallback to regular ticketing + +### 5. Email Templates + +#### Series Pass Confirmation Email +Professional HTML email featuring: +- Purple gradient header +- Full series pass details +- Complete event schedule with dates/times +- Member benefit callout (if applicable) +- Transaction ID (if paid) +- "What's Next" guidance +- Dashboard link + +### 6. UI Integration + +#### Updated Series Detail Page (`/series/[id].vue`) +- New "Get Your Series Pass" section +- Displays SeriesPassPurchase component +- Shows only if `series.tickets.enabled` is true +- Refreshes data after successful purchase +- User session integration + +## Configuration Examples + +### Example 1: Free Member Series, Paid Public + +```javascript +const series = { + id: "coop-game-dev-2025", + title: "Cooperative Game Development Workshop Series", + type: "workshop_series", + tickets: { + enabled: true, + requiresSeriesTicket: true, // Must buy series pass + allowIndividualEventTickets: false, + currency: "CAD", + member: { + available: true, + isFree: true, + name: "Member Series Pass", + description: "Free for Ghost Guild members" + }, + public: { + available: true, + price: 100.00, + earlyBirdPrice: 80.00, + earlyBirdDeadline: "2025-11-01T00:00:00Z", + name: "Public Series Pass", + description: "Access to all 4 workshops" + }, + capacity: { + total: 30 // Total capacity across all ticket types + } + } +} +``` + +### Example 2: Circle-Specific Pricing + +```javascript +const series = { + tickets: { + enabled: true, + member: { + isFree: false, + price: 50.00, // Default member price + circleOverrides: { + community: { + isFree: true // Free for community circle + }, + founder: { + price: 25.00 // Discounted for founders + }, + practitioner: { + price: 10.00 // Heavily discounted + } + } + } + } +} +``` + +### Example 3: Drop-in Series (Individual Event Tickets) + +```javascript +const series = { + id: "monthly-meetup-2025", + title: "Monthly Community Meetup", + type: "recurring_meetup", + tickets: { + enabled: false, // No series-level tickets + requiresSeriesTicket: false, + allowIndividualEventTickets: true + } +} + +// Each event in series has its own tickets config +const event = { + series: { + id: "monthly-meetup-2025", + isSeriesEvent: true + }, + tickets: { + enabled: true, + member: { + isFree: true + }, + public: { + available: true, + price: 10.00 + } + } +} +``` + +## User Flows + +### Flow 1: Member Purchases Free Series Pass + +1. Member visits series page (`/series/coop-game-dev-2025`) +2. Sees "Free for Members" series pass card +3. Fills in name/email (pre-filled from session) +4. Clicks "Complete Registration" +5. System creates series registration +6. System registers user for all 4 events automatically +7. User receives series pass confirmation email with full schedule +8. Page refreshes showing "You're Registered!" status + +### Flow 2: Public User Purchases Paid Series Pass + +1. Public user visits series page +2. Sees "$100 Series Pass" (or $80 early bird) +3. Fills in name/email +4. Clicks "Pay $100.00" +5. Helcim payment modal opens +6. User completes payment +7. System processes payment and creates registrations +8. User receives confirmation email with transaction ID +9. Success toast shows "You're registered for all 4 events" + +### Flow 3: User with Series Pass Views Individual Event + +1. User has series pass for "Coop Game Dev Series" +2. Visits individual event page (`/events/workshop-1`) +3. EventTicketPurchase component checks series access +4. Sees "You're Registered!" with message: + "You have access to this event via your series pass for Cooperative Game Development Workshop Series" +5. No payment or registration required + +### Flow 4: User Without Series Pass Views Required Event + +1. User visits event that requires series pass +2. EventTicketPurchase component detects requirement +3. Sees purple banner: "Series Pass Required" +4. Message explains event is part of series +5. "View Series & Purchase Pass" button +6. Clicking redirects to series page to buy pass + +## Database Schema + +### Series Document Structure + +```javascript +{ + _id: ObjectId, + id: "coop-game-dev-2025", // String identifier + slug: "cooperative-game-development-workshop-series", + title: "Cooperative Game Development Workshop Series", + description: "Learn to build co-op games...", + type: "workshop_series", + isVisible: true, + isActive: true, + startDate: ISODate("2025-11-15"), + endDate: ISODate("2025-12-06"), + totalEvents: 4, + tickets: { + enabled: true, + requiresSeriesTicket: true, + currency: "CAD", + member: { /* ... */ }, + public: { /* ... */ }, + capacity: { total: 30, reserved: 2 } + }, + registrations: [ + { + memberId: ObjectId, + name: "Jane Doe", + email: "jane@example.com", + ticketType: "member", + ticketPrice: 0, + paymentStatus: "not_required", + registeredAt: ISODate, + eventRegistrations: [ + { eventId: ObjectId, registrationId: ObjectId }, + { eventId: ObjectId, registrationId: ObjectId } + ] + } + ], + targetCircles: ["founder", "practitioner"], + createdBy: "admin", + createdAt: ISODate, + updatedAt: ISODate +} +``` + +## Backward Compatibility + +✅ **Fully backward compatible** +- Events without series tickets work as before +- Legacy pricing model still supported +- Existing registrations unaffected +- Series can exist without ticket system enabled + +## Testing Checklist + +### Series Pass Purchase +- [ ] Member can see free series pass +- [ ] Public user sees correct pricing +- [ ] Early bird pricing displays correctly +- [ ] Helcim payment modal opens for paid passes +- [ ] Payment processes successfully +- [ ] All events get registrations created +- [ ] Confirmation email sends with all events listed +- [ ] Capacity decrements correctly + +### Event Access Control +- [ ] User with series pass sees "Registered" on event pages +- [ ] User without pass sees "Series Pass Required" message +- [ ] Link to series page works correctly +- [ ] Individual event tickets disabled when series pass required + +### Edge Cases +- [ ] Already registered users see correct message +- [ ] Sold out series shows waitlist option +- [ ] Cancelled events don't allow registration +- [ ] Payment failures don't create registrations +- [ ] Concurrent purchases don't oversell + +## Future Enhancements + +### Phase 2 (Planned) +- Series pass transfers between users +- Partial series passes ("Any 3 of 5 workshops") +- Upgrade from individual ticket to series pass +- Series pass refunds and cancellations +- Admin dashboard for series pass holders +- Export attendee lists by series + +### Phase 3 (Nice to Have) +- Gift series passes +- Group/team series passes +- Installment payment plans +- Series completion certificates +- Recurring series subscriptions + +## Files Created/Modified + +### New Files (9) +- `server/models/series.js` - Series data model +- `server/api/series/[id]/tickets/available.get.js` - Check availability +- `server/api/series/[id]/tickets/purchase.post.js` - Purchase series pass +- `server/api/series/[id]/tickets/check-eligibility.post.js` - Member check +- `server/api/events/[id]/check-series-access.get.js` - Verify pass ownership +- `app/components/EventSeriesTicketCard.vue` - Series pass display card +- `app/components/SeriesPassPurchase.vue` - Purchase flow component +- `SERIES_TICKETING_IMPLEMENTATION.md` - This documentation + +### Modified Files (4) +- `server/models/event.js` - Added series ticket fields +- `server/utils/tickets.js` - Added 8 series ticket functions (~360 lines) +- `server/utils/resend.js` - Added series pass confirmation email +- `app/components/EventTicketPurchase.vue` - Series pass detection +- `app/pages/series/[id].vue` - Integrated purchase UI + +### Total Implementation +- **~1,200 lines of new code** +- **9 new files** +- **4 modified files** +- **4 new API endpoints** +- **2 new Vue components** +- **8 new utility functions** +- **1 new data model** + +## Support + +For questions or issues: +- Review this documentation +- Check existing ticketing docs: `HELCIM_TICKET_INTEGRATION.md` +- Reference project context: `CLAUDE.md` + +--- + +**Status**: ✅ Implementation Complete +**Last Updated**: 2025-10-14 +**Developer**: Claude (Anthropic) diff --git a/app/components/EventSeriesBadge.vue b/app/components/EventSeriesBadge.vue index 06da070..ed5a512 100644 --- a/app/components/EventSeriesBadge.vue +++ b/app/components/EventSeriesBadge.vue @@ -1,35 +1,33 @@ @@ -477,6 +897,43 @@ const editingSeriesData = ref({ type: "workshop_series", totalEvents: null, }); +const editingTicketsSeriesId = ref(null); +const editingTicketsData = ref({ + title: "", + tickets: { + enabled: false, + requiresSeriesTicket: false, + allowIndividualEventTickets: true, + currency: "CAD", + member: { + available: true, + isFree: true, + price: 0, + name: "Member Series Pass", + description: "", + }, + public: { + available: false, + name: "Series Pass", + description: "", + price: 0, + quantity: null, + sold: 0, + reserved: 0, + earlyBirdPrice: null, + earlyBirdDeadline: "", + }, + capacity: { + total: null, + reserved: 0, + }, + waitlist: { + enabled: false, + maxSize: null, + entries: [], + }, + }, +}); // Fetch series data const { @@ -715,6 +1172,116 @@ const deleteSeries = async (series) => { } }; +// Ticketing management functions +const manageSeriesTickets = (series) => { + editingTicketsSeriesId.value = series.id; + + // Deep clone the series data to avoid mutating the original + editingTicketsData.value = { + title: series.title, + tickets: { + enabled: series.tickets?.enabled || false, + requiresSeriesTicket: series.tickets?.requiresSeriesTicket || false, + allowIndividualEventTickets: + series.tickets?.allowIndividualEventTickets !== false, + currency: series.tickets?.currency || "CAD", + member: { + available: series.tickets?.member?.available !== false, + isFree: series.tickets?.member?.isFree !== false, + price: series.tickets?.member?.price || 0, + name: series.tickets?.member?.name || "Member Series Pass", + description: series.tickets?.member?.description || "", + }, + public: { + available: series.tickets?.public?.available || false, + name: series.tickets?.public?.name || "Series Pass", + description: series.tickets?.public?.description || "", + price: series.tickets?.public?.price || 0, + quantity: series.tickets?.public?.quantity || null, + sold: series.tickets?.public?.sold || 0, + reserved: series.tickets?.public?.reserved || 0, + earlyBirdPrice: series.tickets?.public?.earlyBirdPrice || null, + earlyBirdDeadline: series.tickets?.public?.earlyBirdDeadline + ? new Date(series.tickets.public.earlyBirdDeadline) + .toISOString() + .slice(0, 16) + : "", + }, + capacity: { + total: series.tickets?.capacity?.total || null, + reserved: series.tickets?.capacity?.reserved || 0, + }, + waitlist: { + enabled: series.tickets?.waitlist?.enabled || false, + maxSize: series.tickets?.waitlist?.maxSize || null, + entries: series.tickets?.waitlist?.entries || [], + }, + }, + }; +}; + +const cancelTicketsEdit = () => { + editingTicketsSeriesId.value = null; + editingTicketsData.value = { + title: "", + tickets: { + enabled: false, + requiresSeriesTicket: false, + allowIndividualEventTickets: true, + currency: "CAD", + member: { + available: true, + isFree: true, + price: 0, + name: "Member Series Pass", + description: "", + }, + public: { + available: false, + name: "Series Pass", + description: "", + price: 0, + quantity: null, + sold: 0, + reserved: 0, + earlyBirdPrice: null, + earlyBirdDeadline: "", + }, + capacity: { + total: null, + reserved: 0, + }, + waitlist: { + enabled: false, + maxSize: null, + entries: [], + }, + }, + }; +}; + +const saveTicketsEdit = async () => { + try { + // Update the series with new ticketing configuration + await $fetch("/api/admin/series/tickets", { + method: "PUT", + body: { + id: editingTicketsSeriesId.value, + tickets: editingTicketsData.value.tickets, + }, + }); + + await refresh(); + cancelTicketsEdit(); + alert("Ticketing settings updated successfully"); + } catch (error) { + console.error("Failed to update ticketing settings:", error); + alert( + `Failed to update ticketing settings: ${error.data?.statusMessage || error.message}`, + ); + } +}; + // Bulk operations const reorderAllSeries = async () => { // TODO: Implement auto-reordering diff --git a/app/pages/coming-soon.vue b/app/pages/coming-soon.vue new file mode 100644 index 0000000..a52a3dc --- /dev/null +++ b/app/pages/coming-soon.vue @@ -0,0 +1,14 @@ + + + diff --git a/app/pages/events/[id].vue b/app/pages/events/[id].vue index a8544e5..36ff011 100644 --- a/app/pages/events/[id].vue +++ b/app/pages/events/[id].vue @@ -160,14 +160,14 @@

About the {{ event.series.title }} Series

-

+

{{ event.series.description }}

@@ -227,160 +227,180 @@
- -
+ + + + +
+ +
+
+
+
+

+ You're registered! +

+

+ We've sent a confirmation to your email +

+
+ + Cancel Registration + +
+
+
+ +
+

+ You are logged in, {{ memberData.name }}. +

+ + {{ isRegistering ? "Registering..." : "Register Now" }} + +
+ + +
+

+ Membership Required +

+

+ This event is exclusive to Ghost Guild members. Join any + circle to gain access. +

+
+ + + Become a Member to Register + + +
+ + +
+

+ Register for This Event +

+
-

- You're registered! -

-

- We've sent a confirmation to your email -

-
- - Cancel Registration - -
-
-
- - -
-

- You are logged in, {{ memberData.name }}. -

- - {{ isRegistering ? "Registering..." : "Register Now" }} - -
- - -
-
-

- Membership Required -

-

- This event is exclusive to Ghost Guild members. Join any - circle to gain access. -

-
- - - Become a Member to Register - - -
- - -
-

- Register for This Event -

- -
- - -
- -
- - -
- -
- - -
- -
- - {{ - isRegistering ? "Registering..." : "Register for Event" - }} - -
- -
- - -
-
- Event Capacity -
- - {{ event.registeredCount || 0 }} / {{ event.maxAttendees }} - -
-
+ Full Name + +
+ +
+ + +
+ +
+ + +
+ +
+ + {{ + isRegistering ? "Registering..." : "Register for Event" + }} + +
+ +
+ + +
+
+ Event Capacity +
+ + {{ event.registeredCount || 0 }} / + {{ event.maxAttendees }} + +
+
+
+
@@ -649,6 +669,20 @@ const handleCancelRegistration = async () => { } }; +// Handle ticket purchase success +const handleTicketSuccess = (response) => { + console.log("Ticket purchased successfully:", response); + // Update registered count if needed + if (event.value.registeredCount !== undefined) { + event.value.registeredCount++; + } +}; + +// Handle ticket purchase error +const handleTicketError = (error) => { + console.error("Ticket purchase failed:", error); +}; + // SEO Meta useHead(() => ({ title: event.value diff --git a/app/pages/events/index.vue b/app/pages/events/index.vue index e45fc05..2330ec7 100644 --- a/app/pages/events/index.vue +++ b/app/pages/events/index.vue @@ -60,7 +60,6 @@
-
+

Current Event Series

@@ -140,24 +139,24 @@ v-for="series in activeSeries.slice(0, 6)" :key="series.id" :to="`/series/${series.id}`" - class="block bg-gradient-to-r from-purple-500/10 to-blue-500/10 rounded-xl p-6 border border-purple-500/30 hover:border-purple-500/50 hover:from-purple-500/15 hover:to-blue-500/15 transition-all duration-300" + class="series-list-item block bg-ghost-800/50 dark:bg-ghost-700/30 rounded-xl p-6 border border-ghost-600 dark:border-ghost-600 hover:border-ghost-500 hover:bg-ghost-800/70 dark:hover:bg-ghost-700/50 transition-all duration-300" >
Event Series {{ series.eventCount }} events
{{ series.title }}

{{ series.description }}

-
+
{{ event.series?.position || index + 1 }}
- {{ - event.title - }} + {{ event.title }}
- + {{ formatEventDate(event.startDate) }}
+{{ series.events.length - 3 }} more events
-
+
{{ formatDateRange(series.startDate, series.endDate) }}
diff --git a/app/pages/series/[id].vue b/app/pages/series/[id].vue index 7e1679b..d0d4924 100644 --- a/app/pages/series/[id].vue +++ b/app/pages/series/[id].vue @@ -105,7 +105,7 @@

@@ -117,7 +117,7 @@

@@ -129,7 +129,7 @@

@@ -144,6 +144,30 @@ + +

+ +
+

+ Get Your Series Pass +

+ +
+ +
+
@@ -154,7 +178,7 @@
@@ -170,7 +194,7 @@ {{ event.series?.position || index + 1 }}
@@ -287,12 +311,18 @@ + + +
+

🎫 Your Series Pass is Ready!

+

You're registered for all events

+
+ +
+

Hi ${name},

+ +

+ Great news! Your series pass for ${series.title} is confirmed. + You're now registered for all ${events.length} events in this ${seriesTypeLabels[series.type] || "series"}. +

+ + ${ + ticket.isFree && ticket.type === "member" + ? ` +
+

+ ✨ Member Benefit +

+

+ This series pass is free for Ghost Guild members. Thank you for being part of our community! +

+
+ ` + : "" + } + +
+

Series Pass Details

+ +
+
Series
+
${series.title}
+
+ + ${ + series.description + ? ` +
+
About
+
${series.description}
+
+ ` + : "" + } + +
+
Pass Type
+
${ticket.type === "member" ? "Member Pass" : "Public Pass"}
+
+ +
+
Amount Paid
+
${formatPrice(ticket.price, ticket.currency)}
+
+ + ${ + paymentId + ? ` +
+
Transaction ID
+
${paymentId}
+
+ ` + : "" + } + +
+
Total Events
+
${events.length} events included
+
+
+ +
+

Your Event Schedule

+

+ You're automatically registered for all of these events: +

+ + ${events + .map( + (event, index) => ` +
+
+ Event ${index + 1}: ${event.title} +
+
+ 📅 ${formatDate(event.startDate)} +
+
+ 🕐 ${formatTime(event.startDate, event.endDate)} +
+
+ 📍 ${event.location} +
+
+ `, + ) + .join("")} +
+ + + +
+

What's Next?

+
    +
  • Mark these dates in your calendar
    • +
  • You'll receive individual reminders before each event
    • +
  • Event links and materials will be shared closer to each date
    • +
  • Join the conversation in our Slack community
    • +
+
+
+ +
+

+ Questions? Email us at + events@babyghosts.org +

+

+ Ghost Guild • Building solidarity economies in gaming +

+
+ + + `, + }); + + if (error) { + console.error("Failed to send series pass confirmation email:", error); + return { success: false, error }; + } + + return { success: true, data }; + } catch (error) { + console.error("Error sending series pass confirmation email:", error); + return { success: false, error }; + } +} diff --git a/server/utils/tickets.js b/server/utils/tickets.js new file mode 100644 index 0000000..65e05b8 --- /dev/null +++ b/server/utils/tickets.js @@ -0,0 +1,750 @@ +// Ticket business logic utilities + +/** + * Calculate the applicable ticket price for a user + * @param {Object} event - Event document + * @param {Object} member - Member document (null if not a member) + * @returns {Object} { ticketType, price, currency, isEarlyBird } + */ +export const calculateTicketPrice = (event, member = null) => { + if (!event.tickets?.enabled) { + // Legacy pricing model + if (event.pricing?.paymentRequired && !event.pricing?.isFree) { + return { + ticketType: member ? "member" : "public", + price: member ? 0 : event.pricing.publicPrice, + currency: event.pricing.currency || "CAD", + isEarlyBird: false, + isFree: member ? true : event.pricing.publicPrice === 0, + }; + } + return { + ticketType: "guest", + price: 0, + currency: "CAD", + isEarlyBird: false, + isFree: true, + }; + } + + const now = new Date(); + + // Member pricing + if (member && event.tickets.member?.available) { + const memberTicket = event.tickets.member; + let price = memberTicket.price || 0; + let isFree = memberTicket.isFree; + + // Check for circle-specific overrides + if (memberTicket.circleOverrides && member.circle) { + const circleOverride = memberTicket.circleOverrides[member.circle]; + if (circleOverride) { + if (circleOverride.isFree !== undefined) { + isFree = circleOverride.isFree; + } + if (circleOverride.price !== undefined) { + price = circleOverride.price; + } + } + } + + return { + ticketType: "member", + price: isFree ? 0 : price, + currency: event.tickets.currency || "CAD", + isEarlyBird: false, + isFree, + name: memberTicket.name || "Member Ticket", + description: memberTicket.description, + }; + } + + // Public pricing + if (event.tickets.public?.available) { + const publicTicket = event.tickets.public; + let price = publicTicket.price || 0; + let isEarlyBird = false; + + // Check for early bird pricing + if ( + publicTicket.earlyBirdPrice !== undefined && + publicTicket.earlyBirdDeadline && + now < new Date(publicTicket.earlyBirdDeadline) + ) { + price = publicTicket.earlyBirdPrice; + isEarlyBird = true; + } + + return { + ticketType: "public", + price, + currency: event.tickets.currency || "CAD", + isEarlyBird, + isFree: price === 0, + name: publicTicket.name || "Public Ticket", + description: publicTicket.description, + }; + } + + // No tickets available (members only event, user not a member) + return null; +}; + +/** + * Check if tickets are available for an event + * @param {Object} event - Event document + * @param {String} ticketType - 'member' or 'public' + * @returns {Object} { available, remaining, waitlistAvailable } + */ +export const checkTicketAvailability = (event, ticketType = "public") => { + if (!event.tickets?.enabled) { + // Legacy registration system + if (!event.maxAttendees) { + return { available: true, remaining: null, waitlistAvailable: false }; + } + + const registered = event.registrations?.length || 0; + const remaining = event.maxAttendees - registered; + + return { + available: remaining > 0, + remaining: Math.max(0, remaining), + waitlistAvailable: event.tickets?.waitlist?.enabled || false, + }; + } + + const registered = event.registrations?.length || 0; + + // Check overall capacity first + if (event.tickets.capacity?.total) { + const totalRemaining = event.tickets.capacity.total - registered; + if (totalRemaining <= 0) { + return { + available: false, + remaining: 0, + waitlistAvailable: event.tickets.waitlist?.enabled || false, + }; + } + } + + // Check ticket-type specific availability + if (ticketType === "public" && event.tickets.public?.available) { + if (event.tickets.public.quantity) { + const sold = event.tickets.public.sold || 0; + const reserved = event.tickets.public.reserved || 0; + const remaining = event.tickets.public.quantity - sold - reserved; + + return { + available: remaining > 0, + remaining: Math.max(0, remaining), + waitlistAvailable: event.tickets.waitlist?.enabled || false, + }; + } + // Unlimited public tickets + return { available: true, remaining: null, waitlistAvailable: false }; + } + + if (ticketType === "member" && event.tickets.member?.available) { + // Members typically have unlimited access unless capacity is reached + if (event.tickets.capacity?.total) { + const totalRemaining = event.tickets.capacity.total - registered; + return { + available: totalRemaining > 0, + remaining: Math.max(0, totalRemaining), + waitlistAvailable: event.tickets.waitlist?.enabled || false, + }; + } + // Unlimited member tickets + return { available: true, remaining: null, waitlistAvailable: false }; + } + + return { available: false, remaining: 0, waitlistAvailable: false }; +}; + +/** + * Validate if a user can purchase a ticket + * @param {Object} event - Event document + * @param {Object} user - User data { email, name, member } + * @returns {Object} { valid, reason, ticketInfo } + */ +export const validateTicketPurchase = (event, user) => { + // Check if event is cancelled + if (event.isCancelled) { + return { valid: false, reason: "Event has been cancelled" }; + } + + // Check if event has passed + if (new Date(event.startDate) < new Date()) { + return { valid: false, reason: "Event has already started" }; + } + + // Check if registration deadline has passed + if ( + event.registrationDeadline && + new Date(event.registrationDeadline) < new Date() + ) { + return { valid: false, reason: "Registration deadline has passed" }; + } + + // Check if user is already registered + const alreadyRegistered = event.registrations?.some( + (reg) => + reg.email.toLowerCase() === user.email.toLowerCase() && !reg.cancelledAt, + ); + + if (alreadyRegistered) { + return { + valid: false, + reason: "You are already registered for this event", + }; + } + + // Check member-only restrictions + if (event.membersOnly && !user.member) { + return { + valid: false, + reason: "This event is for members only. Please join to register.", + }; + } + + // Calculate ticket price and check availability + const ticketInfo = calculateTicketPrice(event, user.member); + + if (!ticketInfo) { + return { + valid: false, + reason: "No tickets available for your membership status", + }; + } + + const availability = checkTicketAvailability(event, ticketInfo.ticketType); + + if (!availability.available) { + return { + valid: false, + reason: "Event is sold out", + waitlistAvailable: availability.waitlistAvailable, + }; + } + + return { + valid: true, + ticketInfo, + availability, + }; +}; + +/** + * Reserve a ticket temporarily during checkout (prevents race conditions) + * @param {Object} event - Event document + * @param {String} ticketType - 'member' or 'public' + * @param {Number} ttl - Time to live in seconds (default 10 minutes) + * @returns {Object} { success, reservationId, expiresAt } + */ +export const reserveTicket = async (event, ticketType, ttl = 600) => { + const availability = checkTicketAvailability(event, ticketType); + + if (!availability.available) { + return { + success: false, + reason: "No tickets available", + }; + } + + // Increment reserved count + if (ticketType === "public" && event.tickets.public) { + event.tickets.public.reserved = (event.tickets.public.reserved || 0) + 1; + } + + if (event.tickets.capacity) { + event.tickets.capacity.reserved = + (event.tickets.capacity.reserved || 0) + 1; + } + + await event.save(); + + const expiresAt = new Date(Date.now() + ttl * 1000); + + return { + success: true, + reservationId: `${event._id}-${ticketType}-${Date.now()}`, + expiresAt, + }; +}; + +/** + * Release a reserved ticket (if payment fails or user abandons checkout) + * @param {Object} event - Event document + * @param {String} ticketType - 'member' or 'public' + */ +export const releaseTicket = async (event, ticketType) => { + if (ticketType === "public" && event.tickets.public) { + event.tickets.public.reserved = Math.max( + 0, + (event.tickets.public.reserved || 0) - 1, + ); + } + + if (event.tickets.capacity) { + event.tickets.capacity.reserved = Math.max( + 0, + (event.tickets.capacity.reserved || 0) - 1, + ); + } + + await event.save(); +}; + +/** + * Complete ticket purchase (after successful payment) + * @param {Object} event - Event document + * @param {String} ticketType - 'member' or 'public' + */ +export const completeTicketPurchase = async (event, ticketType) => { + // Decrement reserved count + await releaseTicket(event, ticketType); + + // Increment sold count for public tickets + if (ticketType === "public" && event.tickets.public) { + event.tickets.public.sold = (event.tickets.public.sold || 0) + 1; + } + + await event.save(); +}; + +/** + * Add user to waitlist + * @param {Object} event - Event document + * @param {Object} userData - { name, email, membershipLevel } + * @returns {Object} { success, position } + */ +export const addToWaitlist = async (event, userData) => { + if (!event.tickets?.waitlist?.enabled) { + return { success: false, reason: "Waitlist is not enabled for this event" }; + } + + // Check if already on waitlist + const alreadyOnWaitlist = event.tickets.waitlist.entries?.some( + (entry) => entry.email.toLowerCase() === userData.email.toLowerCase(), + ); + + if (alreadyOnWaitlist) { + return { success: false, reason: "You are already on the waitlist" }; + } + + // Check waitlist capacity + const maxSize = event.tickets.waitlist.maxSize; + const currentSize = event.tickets.waitlist.entries?.length || 0; + + if (maxSize && currentSize >= maxSize) { + return { success: false, reason: "Waitlist is full" }; + } + + // Add to waitlist + if (!event.tickets.waitlist.entries) { + event.tickets.waitlist.entries = []; + } + + event.tickets.waitlist.entries.push({ + name: userData.name, + email: userData.email.toLowerCase(), + membershipLevel: userData.membershipLevel || "non-member", + addedAt: new Date(), + notified: false, + }); + + await event.save(); + + return { + success: true, + position: event.tickets.waitlist.entries.length, + }; +}; + +/** + * Format price for display + * @param {Number} price - Price in cents or dollars + * @param {String} currency - Currency code (default CAD) + * @returns {String} Formatted price string + */ +export const formatPrice = (price, currency = "CAD") => { + if (price === 0) return "Free"; + + return new Intl.NumberFormat("en-CA", { + style: "currency", + currency, + }).format(price); +}; + +// ============================================================================ +// SERIES TICKET FUNCTIONS +// ============================================================================ + +/** + * Calculate the applicable series pass price for a user + * @param {Object} series - Series document + * @param {Object} member - Member document (null if not a member) + * @returns {Object} { ticketType, price, currency, isEarlyBird } + */ +export const calculateSeriesTicketPrice = (series, member = null) => { + if (!series.tickets?.enabled) { + return { + ticketType: "guest", + price: 0, + currency: "CAD", + isEarlyBird: false, + isFree: true, + }; + } + + const now = new Date(); + + // Member pricing + if (member && series.tickets.member?.available) { + const memberTicket = series.tickets.member; + let price = memberTicket.price || 0; + let isFree = memberTicket.isFree; + + // Check for circle-specific overrides + if (memberTicket.circleOverrides && member.circle) { + const circleOverride = memberTicket.circleOverrides[member.circle]; + if (circleOverride) { + if (circleOverride.isFree !== undefined) { + isFree = circleOverride.isFree; + } + if (circleOverride.price !== undefined) { + price = circleOverride.price; + } + } + } + + return { + ticketType: "member", + price: isFree ? 0 : price, + currency: series.tickets.currency || "CAD", + isEarlyBird: false, + isFree, + name: memberTicket.name || "Member Series Pass", + description: memberTicket.description, + }; + } + + // Public pricing + if (series.tickets.public?.available) { + const publicTicket = series.tickets.public; + let price = publicTicket.price || 0; + let isEarlyBird = false; + + // Check for early bird pricing + if ( + publicTicket.earlyBirdPrice !== undefined && + publicTicket.earlyBirdDeadline && + now < new Date(publicTicket.earlyBirdDeadline) + ) { + price = publicTicket.earlyBirdPrice; + isEarlyBird = true; + } + + return { + ticketType: "public", + price, + currency: series.tickets.currency || "CAD", + isEarlyBird, + isFree: price === 0, + name: publicTicket.name || "Series Pass", + description: publicTicket.description, + }; + } + + // No tickets available + return null; +}; + +/** + * Check if series passes are available + * @param {Object} series - Series document + * @param {String} ticketType - 'member' or 'public' + * @returns {Object} { available, remaining, waitlistAvailable } + */ +export const checkSeriesTicketAvailability = ( + series, + ticketType = "public", +) => { + if (!series.tickets?.enabled) { + return { available: false, remaining: 0, waitlistAvailable: false }; + } + + const registered = + series.registrations?.filter((r) => !r.cancelledAt).length || 0; + + // Check overall capacity first + if (series.tickets.capacity?.total) { + const totalRemaining = series.tickets.capacity.total - registered; + if (totalRemaining <= 0) { + return { + available: false, + remaining: 0, + waitlistAvailable: series.tickets.waitlist?.enabled || false, + }; + } + } + + // Check ticket-type specific availability + if (ticketType === "public" && series.tickets.public?.available) { + if (series.tickets.public.quantity) { + const sold = series.tickets.public.sold || 0; + const reserved = series.tickets.public.reserved || 0; + const remaining = series.tickets.public.quantity - sold - reserved; + + return { + available: remaining > 0, + remaining: Math.max(0, remaining), + waitlistAvailable: series.tickets.waitlist?.enabled || false, + }; + } + // Unlimited public tickets + return { available: true, remaining: null, waitlistAvailable: false }; + } + + if (ticketType === "member" && series.tickets.member?.available) { + // Members typically have unlimited access unless capacity is reached + if (series.tickets.capacity?.total) { + const totalRemaining = series.tickets.capacity.total - registered; + return { + available: totalRemaining > 0, + remaining: Math.max(0, totalRemaining), + waitlistAvailable: series.tickets.waitlist?.enabled || false, + }; + } + // Unlimited member tickets + return { available: true, remaining: null, waitlistAvailable: false }; + } + + return { available: false, remaining: 0, waitlistAvailable: false }; +}; + +/** + * Validate if a user can purchase a series pass + * @param {Object} series - Series document + * @param {Object} user - User data { email, name, member } + * @returns {Object} { valid, reason, ticketInfo } + */ +export const validateSeriesTicketPurchase = (series, user) => { + // Check if series is active + if (!series.isActive) { + return { valid: false, reason: "This series is not currently available" }; + } + + // Check if user is already registered for the series + const alreadyRegistered = series.registrations?.some( + (reg) => + reg.email.toLowerCase() === user.email.toLowerCase() && !reg.cancelledAt, + ); + + if (alreadyRegistered) { + return { valid: false, reason: "You already have a pass for this series" }; + } + + // Calculate ticket price and check availability + const ticketInfo = calculateSeriesTicketPrice(series, user.member); + + if (!ticketInfo) { + return { + valid: false, + reason: "No series passes available for your membership status", + }; + } + + const availability = checkSeriesTicketAvailability( + series, + ticketInfo.ticketType, + ); + + if (!availability.available) { + return { + valid: false, + reason: "Series passes are sold out", + waitlistAvailable: availability.waitlistAvailable, + }; + } + + return { + valid: true, + ticketInfo, + availability, + }; +}; + +/** + * Reserve a series pass temporarily during checkout + * @param {Object} series - Series document + * @param {String} ticketType - 'member' or 'public' + * @param {Number} ttl - Time to live in seconds (default 10 minutes) + * @returns {Object} { success, reservationId, expiresAt } + */ +export const reserveSeriesTicket = async (series, ticketType, ttl = 600) => { + const availability = checkSeriesTicketAvailability(series, ticketType); + + if (!availability.available) { + return { + success: false, + reason: "No series passes available", + }; + } + + // Increment reserved count + if (ticketType === "public" && series.tickets.public) { + series.tickets.public.reserved = (series.tickets.public.reserved || 0) + 1; + } + + if (series.tickets.capacity) { + series.tickets.capacity.reserved = + (series.tickets.capacity.reserved || 0) + 1; + } + + await series.save(); + + const expiresAt = new Date(Date.now() + ttl * 1000); + + return { + success: true, + reservationId: `${series._id}-${ticketType}-${Date.now()}`, + expiresAt, + }; +}; + +/** + * Release a reserved series pass + * @param {Object} series - Series document + * @param {String} ticketType - 'member' or 'public' + */ +export const releaseSeriesTicket = async (series, ticketType) => { + if (ticketType === "public" && series.tickets.public) { + series.tickets.public.reserved = Math.max( + 0, + (series.tickets.public.reserved || 0) - 1, + ); + } + + if (series.tickets.capacity) { + series.tickets.capacity.reserved = Math.max( + 0, + (series.tickets.capacity.reserved || 0) - 1, + ); + } + + await series.save(); +}; + +/** + * Complete series pass purchase (after successful payment) + * @param {Object} series - Series document + * @param {String} ticketType - 'member' or 'public' + */ +export const completeSeriesTicketPurchase = async (series, ticketType) => { + // Decrement reserved count + await releaseSeriesTicket(series, ticketType); + + // Increment sold count for public tickets + if (ticketType === "public" && series.tickets.public) { + series.tickets.public.sold = (series.tickets.public.sold || 0) + 1; + } + + await series.save(); +}; + +/** + * Check if a user has a valid series pass for a series + * @param {Object} series - Series document + * @param {String} userEmail - User email to check + * @returns {Object} { hasPass, registration } + */ +export const checkUserSeriesPass = (series, userEmail) => { + const registration = series.registrations?.find( + (reg) => + reg.email.toLowerCase() === userEmail.toLowerCase() && + !reg.cancelledAt && + reg.paymentStatus !== "failed", + ); + + return { + hasPass: !!registration, + registration: registration || null, + }; +}; + +/** + * Register user for all events in a series using their series pass + * @param {Object} series - Series document + * @param {Array} events - Array of event documents in the series + * @param {Object} seriesRegistration - The series pass registration + * @returns {Array} Array of event registration results + */ +export const registerForAllSeriesEvents = async ( + series, + events, + seriesRegistration, +) => { + const results = []; + + for (const event of events) { + try { + // Check if already registered for this event + const alreadyRegistered = event.registrations?.some( + (reg) => + reg.email.toLowerCase() === seriesRegistration.email.toLowerCase() && + !reg.cancelledAt, + ); + + if (alreadyRegistered) { + results.push({ + eventId: event._id, + success: false, + reason: "Already registered", + }); + continue; + } + + // Add registration to event + event.registrations.push({ + memberId: seriesRegistration.memberId, + name: seriesRegistration.name, + email: seriesRegistration.email, + membershipLevel: seriesRegistration.membershipLevel, + isMember: seriesRegistration.isMember, + ticketType: "series_pass", + ticketPrice: 0, // Already paid at series level + isSeriesTicketHolder: true, + seriesTicketId: series._id, + paymentStatus: "not_required", // Paid at series level + registeredAt: new Date(), + }); + + await event.save(); + + // Update series registration with event reference + const eventReg = event.registrations[event.registrations.length - 1]; + seriesRegistration.eventRegistrations.push({ + eventId: event._id, + registrationId: eventReg._id, + }); + + results.push({ + eventId: event._id, + success: true, + registrationId: eventReg._id, + }); + } catch (error) { + results.push({ + eventId: event._id, + success: false, + reason: error.message, + }); + } + } + + // Save series with updated event registrations + await series.save(); + + return results; +};