# Meter Signups - Magic Link Activation Setup

## What Was Built

We've implemented a modern SaaS-style trial signup flow with magic link activation:

1. **User signs up** with just email, first name, last name
2. **Receives activation email** with magic link
3. **Clicks link** to set their password
4. **Automatically logged in** and redirected to welcome page
5. **7-day trial** starts immediately

---

## ⚠️ CRITICAL: Setup Steps (Do In Order!)

### 1. Update the Welcome Email Template **[MUST DO FIRST!]**

The email template is stored in your WordPress database. **You MUST update it or the magic link won't work.**

**Run the Update Script:**
1. Go to: `https://yourdomain.com/wp-content/plugins/meter-signups/includes/update-email-template.php`
2. You should see "Success!" message
3. **Delete the script file after running it** for security: `wp-content/plugins/meter-signups/includes/update-email-template.php`

**If script doesn't work, Manual Update:**
1. Go to WordPress Admin → Email Templates
2. Find "Welcome Email"
3. Click Edit
4. Replace the entire body with:

```
Welcome to Meter Search!

Dear {first_name},

You're one step away from starting your 7-day free trial of Meter Search.

<a href="{activation_url}" style="display: inline-block; background: #0073aa; color: white; padding: 15px 30px; text-decoration: none; border-radius: 5px; font-weight: bold; margin: 20px 0;">Activate My Trial & Set Password</a>

This link will:
✓ Verify your email address
✓ Let you create your password
✓ Give you instant access to Meter Search

Your 7-day trial includes:
- Full access to government vendor search
- Comprehensive market research tools
- Contract intelligence and analysis
- Competitive insights

Your trial ends on {trial_end_date}.

Questions? Just reply to this email.

Best regards,
The {site_name} Team
```

5. Update the subject to: **"Activate Your 7-Day Meter Search Trial"**
6. Save

### 2. Create the Activation Page

1. Go to WordPress Admin → Pages → Add New
2. Title: "Activate Trial" (or whatever you want)
3. URL slug: `activate-trial` (IMPORTANT - must match the code)
4. Content: Add the shortcode: `[meter_trial_activation]`
5. Publish

### 3. Create the Welcome Page

1. Go to WordPress Admin → Pages → Add New
2. Title: "Welcome" (or "Trial Welcome")
3. URL slug: `trial-welcome` (IMPORTANT - must match the code)
4. Content: Add the shortcode: `[meter_trial_welcome meter_search_url="/your-meter-search-page/"]`
   - Replace `/your-meter-search-page/` with the actual URL to your Meter Search tool
5. Publish

### 4. Update Your Signup Page

Make sure your signup page has:
```
[meter_trial_signup]
```

This shortcode already exists and has been updated to work with the new activation flow.

### 5. Clear All Caches

**IMPORTANT:** After setup, clear all caches:
1. Go to Meter Search → Settings
2. Scroll to bottom
3. Click "💥 Flush All Caches Now"
4. If using Cloudflare, purge there too

---

## Testing the Flow

### Test the Complete Signup Flow:

1. **Sign up**: Go to your signup page and create a test account
2. **Check email**: You should receive "Activate Your 7-Day Meter Search Trial"
3. **Click activation link**: Should go to `/activate-trial/` page
4. **Set password**: Create your password (min 8 characters)
5. **Submit**: Should auto-login and redirect to `/trial-welcome/`
6. **Verify trial**: Welcome page should show "7 days remaining"

### What to Check:

- [ ] Email arrives with correct subject line
- [ ] Email says "7-day" not "30-day"
- [ ] Activation link works (doesn't 404)
- [ ] Password form appears
- [ ] Can set password successfully
- [ ] Auto-logged in after setting password
- [ ] Redirected to welcome page
- [ ] Welcome page shows trial info correctly
- [ ] "Get Started" button links to Meter Search

---

## Shortcodes Reference

### `[meter_trial_signup]`
The main signup form.

**Attributes:**
- `title` - Form title (default: "Start your 7-day free trial")
- `button_text` - Submit button text (default: "Start My Free Trial")
- `success_message` - Success message after signup

**Example:**
```
[meter_trial_signup title="Get Started Free" button_text="Start Now"]
```

### `[meter_trial_activation]`
The activation page where users set their password.

**Attributes:**
- `title` - Page title (default: "Activate Your Trial")

**Example:**
```
[meter_trial_activation title="Set Your Password"]
```

### `[meter_trial_welcome]`
The welcome page shown after activation.

**Attributes:**
- `title` - Welcome title (default: "Welcome to Meter Search!")
- `meter_search_url` - URL to your Meter Search tool (default: "/meter-search/")
- `button_text` - CTA button text (default: "Start Exploring Meter Search")

**Example:**
```
[meter_trial_welcome meter_search_url="/dashboard/" button_text="Go to Dashboard"]
```

---

## Email Template Variables

Available variables in email templates:

- `{first_name}` - User's first name
- `{user_name}` - User's display name
- `{trial_end_date}` - When trial expires (formatted)
- `{days_remaining}` - Days left in trial
- `{site_name}` - Your site name
- `{login_url}` - WordPress login URL
- `{activation_url}` - **NEW** - Magic link to activate account

---

## Troubleshooting

### Receiving multiple copies of email (3+ emails)
**FIXED in latest version!** If you're still seeing this:
- Make sure you have the latest code (duplicate email sending was removed)
- Clear all caches (Meter Search → Settings → Flush All Caches)
- Delete test users and try again with fresh signup

### Still getting old "30-day" template
- **You must run the email template update script!** This is not optional.
- Visit: `yourdomain.com/wp-content/plugins/meter-signups/includes/update-email-template.php`
- The template is stored in the database, not in PHP files
- Code changes alone won't update the email template

### "Activation link expired"
- Links expire after 24 hours
- User needs to contact support for a new link
- Future: Add "resend activation email" feature

### "Activation link invalid"
- Link may have been already used
- User may have mistyped the URL
- Check if activation token exists in user meta

### Email not arriving
- Check spam folder
- Verify WordPress can send emails (install WP Mail SMTP if needed)
- Check email template exists in database

### Page not found (404)
- Make sure you created the pages with correct slugs:
  - `/activate-trial/`
  - `/trial-welcome/`
- Clear permalinks: Settings → Permalinks → Save Changes

### Still showing "30-day"
- Run the email template update script
- Clear all caches (use the emergency cache flush button)
- Check the database template content directly

---

## Files Modified/Created

### New Files:
- `/includes/class-activation-handler.php` - Handles activation flow
- `/includes/class-welcome-page.php` - Welcome page shortcode
- `/includes/update-email-template.php` - One-time script to update email

### Modified Files:
- `/includes/class-signup-shortcode.php` - Added token generation
- `/includes/class-email-sender.php` - Added activation URL variable
- `/meter-signups.php` - Loaded new classes

---

## Next Steps

After testing and confirming the flow works:

1. **Delete the update script** for security:
   - Delete: `/includes/update-email-template.php`

2. **Customize the pages** to match your branding

3. **Set up Stripe integration** (future phase) to handle post-trial subscriptions

4. **Add "resend activation email"** feature (optional enhancement)

---

## Support

If you encounter issues:
1. Check error logs: `/wp-content/debug.log`
2. Verify all shortcodes are in place
3. Clear caches aggressively
4. Test with a fresh browser/incognito mode