284 lines
8.5 KiB
Markdown
284 lines
8.5 KiB
Markdown
# 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)
|