Add landing page
This commit is contained in:
parent
3fea484585
commit
bce86ee840
47 changed files with 7119 additions and 439 deletions
284
HELCIM_TICKET_INTEGRATION.md
Normal file
284
HELCIM_TICKET_INTEGRATION.md
Normal file
|
|
@ -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)
|
||||
Loading…
Add table
Add a link
Reference in a new issue