mirror of
https://github.com/jjbrunton/Sauci.git
synced 2026-10-31 18:19:43 +00:00
74 lines
2.8 KiB
Markdown
74 lines
2.8 KiB
Markdown
# Agents Documentation
|
|
|
|
This file contains important project-specific context for Claude Code agents working on this repository.
|
|
|
|
## Redemption Code System
|
|
|
|
**IMPORTANT: Codes can only be redeemed on the website, NOT in the mobile app.**
|
|
|
|
Apple's App Store guidelines require that any premium features purchased within an iOS app must go through In-App Purchase. Adding a redemption code feature to the mobile app would violate these guidelines and risk app rejection.
|
|
|
|
### Overview
|
|
Promotional codes that grant users premium access without going through RevenueCat/App Store subscription flow.
|
|
|
|
### Database Schema
|
|
|
|
**`redemption_codes` table:**
|
|
- `id` (UUID) - Primary key
|
|
- `code` (TEXT, UNIQUE) - The redemption code
|
|
- `description` (TEXT) - Optional description
|
|
- `max_uses` (INTEGER) - Maximum number of redemptions allowed
|
|
- `current_uses` (INTEGER) - Current number of redemptions
|
|
- `expires_at` (TIMESTAMPTZ) - Optional expiration date
|
|
- `is_active` (BOOLEAN) - Whether the code can be redeemed
|
|
- `created_by` (UUID) - Admin who created the code
|
|
- `created_at` (TIMESTAMPTZ)
|
|
- `updated_at` (TIMESTAMPTZ)
|
|
|
|
**`code_redemptions` table:**
|
|
- `id` (UUID) - Primary key
|
|
- `code_id` (UUID) - Reference to redemption_codes
|
|
- `user_id` (UUID) - User who redeemed the code
|
|
- `redeemed_at` (TIMESTAMPTZ)
|
|
- UNIQUE constraint on (code_id, user_id) - Each user can only redeem a code once
|
|
|
|
### Components
|
|
|
|
1. **Admin UI** (`apps/admin/src/pages/RedemptionCodesPage.tsx`)
|
|
- Super admins can generate codes
|
|
- View all codes with usage stats
|
|
- Toggle active/inactive
|
|
- View who redeemed each code
|
|
- Delete codes
|
|
|
|
2. **Edge Function** (`apps/supabase/functions/redeem-code/index.ts`)
|
|
- **Unauthenticated** - accepts email + code in request body
|
|
- Calls the `redeem_code_by_email()` database function
|
|
- Returns success/error response
|
|
|
|
3. **Database Function** (`redeem_code_by_email(p_email TEXT, p_code TEXT)`)
|
|
- Atomic operation with row locking
|
|
- Looks up user by email (must have signed up in app first)
|
|
- Validates: code exists, is active, not expired, has uses remaining
|
|
- Checks user hasn't already redeemed
|
|
- Records redemption in `code_redemptions`
|
|
- Increments `current_uses`
|
|
- Sets `profiles.is_premium = true`
|
|
|
|
4. **Web UI** (`apps/web/app/redeem/page.tsx`)
|
|
- Public page at `/redeem`
|
|
- User enters email + redemption code
|
|
- Calls edge function via fetch
|
|
- Shows success or error message
|
|
|
|
### Environment Variables
|
|
|
|
The web app requires:
|
|
- `NEXT_PUBLIC_SUPABASE_URL` - Supabase project URL for API calls
|
|
|
|
### DO NOT
|
|
|
|
- **DO NOT** add redemption code UI to the mobile app
|
|
- **DO NOT** create any in-app mechanism to bypass App Store purchases
|
|
- **DO NOT** expose the redeem endpoint in mobile app Supabase calls
|