# Subscription Feature

Frontend UI for subscription management with Stripe integration.

## Overview

Provides subscription tier management, payment method updates, billing history, donations, and vehicle selection during downgrade flow.

## Components

### TierCard
Subscription plan display with:
- Plan name and pricing (monthly/yearly toggle)
- Feature list
- Current plan indicator
- Upgrade/downgrade button

### PaymentMethodForm
Stripe Elements integration for:
- Credit card input with CardElement
- Real-time validation
- Payment method creation
- Error handling

### BillingHistory
Invoice list with:
- Date, amount, status
- PDF download links
- MUI Table component

### VehicleSelectionDialog
Vehicle selection during downgrade:
- Checkbox list for each vehicle
- Counter showing selected vs allowed
- Warning about tier-gated vehicles
- Validation preventing over-selection

### DowngradeFlow
Orchestrates downgrade process:
- Checks vehicle count vs target tier limit
- Shows VehicleSelectionDialog if needed
- Submits vehicle selections to backend

### DonationSection / DonationSectionMobile
One-time donation form:
- Free-form amount input (no presets)
- $0.50 minimum (Stripe limit)
- Stripe CardElement for payment
- Donation history table
- Success feedback

## Pages

### SubscriptionPage (Desktop)
MUI-based layout:
- Current plan card with status badges
- Three-column tier comparison
- Monthly/yearly toggle
- Payment method modal
- Billing history table
- Donation section

### SubscriptionMobileScreen (Mobile)
Tailwind-based layout:
- GlassCard styling
- Stacked card layout
- Touch-friendly buttons (44px min)
- Modal payment forms

## API Integration

### Subscriptions
| Endpoint | Method | Hook |
|----------|--------|------|
| /api/subscriptions | GET | useSubscription() |
| /api/subscriptions/checkout | POST | useCheckout() |
| /api/subscriptions/cancel | POST | useCancelSubscription() |
| /api/subscriptions/reactivate | POST | useReactivateSubscription() |
| /api/subscriptions/downgrade | POST | useDowngrade() |
| /api/subscriptions/payment-method | PUT | useUpdatePaymentMethod() |
| /api/subscriptions/invoices | GET | useInvoices() |

### Donations
| Endpoint | Method | Hook |
|----------|--------|------|
| /api/donations | POST | useCreateDonation() |
| /api/donations | GET | useDonations() |

## Hooks

| Hook | Purpose |
|------|---------|
| useSubscription() | Fetch current subscription |
| useCheckout() | Upgrade subscription |
| useCancelSubscription() | Cancel subscription |
| useReactivateSubscription() | Reactivate subscription |
| useDowngrade() | Downgrade with vehicle selection |
| useInvoices() | Fetch billing history |
| useCreateDonation() | Create donation payment |
| useDonations() | Fetch donation history |

## Environment Variables

```bash
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
```

## Subscription Tiers

### Free ($0)
- 2 vehicles
- Basic tracking
- Standard reports

### Pro ($1.99/month or $19.99/year)
- Up to 5 vehicles
- VIN decoding
- OCR functionality
- API access

### Enterprise ($4.99/month or $49.99/year)
- Unlimited vehicles
- All Pro features
- Priority support

## Routing

- Desktop: `/garage/settings/subscription`
- Mobile: `navigateToScreen('Subscription')`

## Files

| File | Purpose |
|------|---------|
| types/subscription.types.ts | TypeScript interfaces |
| api/subscription.api.ts | API client calls |
| hooks/useSubscription.ts | React Query hooks |
| constants/plans.ts | Tier configuration |
| components/TierCard.tsx | Plan display card |
| components/PaymentMethodForm.tsx | Stripe Elements form |
| components/BillingHistory.tsx | Invoice table |
| components/VehicleSelectionDialog.tsx | Vehicle selection modal |
| components/DowngradeFlow.tsx | Downgrade orchestrator |
| components/DonationSection.tsx | Desktop donation UI |
| components/DonationSectionMobile.tsx | Mobile donation UI |
| pages/SubscriptionPage.tsx | Desktop page |
| mobile/SubscriptionMobileScreen.tsx | Mobile screen |

## Testing

1. View current plan
2. Toggle monthly/yearly billing
3. Upgrade: Select tier, enter payment, complete checkout
4. Downgrade: Select vehicles to keep if over limit
5. Cancel/reactivate subscription
6. Make a donation
7. View billing and donation history
