License Key Formats - PhotoFlow SEO Pro

📋 Supported Formats

PhotoFlow SEO Pro supports two license key formats:

1. UUID Format (Lemon Squeezy Default) ✅ Recommended

Format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Example: 12345678-1234-1234-1234-123456789ABC

When to use:

• ✅ Default Lemon Squeezy configuration
• ✅ No custom prefix setup required
• ✅ Immediate setup, no configuration needed
• ✅ Most common for new products

How Lemon Squeezy generates this:

1. Create product in Lemon Squeezy
2. Enable "License Keys" toggle
3. Lemon Squeezy automatically generates UUID-format keys
4. No additional configuration needed!

---

2. Custom Prefix Format (Optional)

Format: pswp_XXXX_XXXXXXXXXXXX

Examples:

• Production: pswp_prod_abc123def456
• Demo: pswp_demo_test1234

When to use:

• ⚠️ Only if you set up custom prefix in Lemon Squeezy
• ⚠️ Requires additional configuration
• ⚠️ Not available in all Lemon Squeezy accounts

How to set up (if available):

1. Go to Lemon Squeezy → Product → License Keys
2. Look for "Custom Format" or "Prefix" setting
3. Set prefix to: pswp_prod_
4. Save changes

Note: This setting may not be available in all Lemon Squeezy accounts. If you can't find it, use the UUID format instead!

---

🔧 Validation Logic

Client-Side (src/pro/license.js)

export function isLicenseValidLocally(key) {
  if (!key || typeof key !== 'string') return false;
  
  // Accept both formats:
  // 1. pswp_* format (custom prefix)
  const pswpFormat = /^pswp_[a-z0-9_]{4,}$/i.test(key);
  
  // 2. UUID format (Lemon Squeezy default)
  const uuidFormat = /^[A-F0-9]{8}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{12}$/i.test(key);
  
  return pswpFormat || uuidFormat;
}

Server-Side (server/lemonsqueezy/router.js)

// Validates UUID format for Lemon Squeezy API
const uuidRegex = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;

if (!uuidRegex.test(licenseKey)) {
  return res.status(400).json({ error: 'invalid_license_format' });
}

---

📦 What Customers See

In Purchase Email:

YOUR LICENSE KEY:
12345678-1234-1234-1234-123456789ABC

(Save this - you'll need it to activate Pro features)

In Code:

import { createAiSeoPlugin } from 'photoswipe-pro';

const aiPlugin = createAiSeoPlugin({
  licenseKey: '12345678-1234-1234-1234-123456789ABC',
  baseUrl: '/api/ai'
});

In Customer Portal:

🔑 License: 12345678-1234-1234-1234-123456789ABC
📧 Email: customer@example.com
✅ Status: Active

---

🎯 Recommended Setup

For New Installations:

1. Use UUID format (Lemon Squeezy default)
2. No custom prefix configuration needed
3. Faster setup, less complexity
4. Fully supported by validation logic

Setup Steps:

1. Create product in Lemon Squeezy
2. Enable "License Keys" toggle ✅
3. Stop here! Lemon Squeezy will use UUID format
4. Test with a purchase - key will be UUID format
5. Verify in webhook that license_key is UUID

---

🔄 Migration Guide

If You're Using Custom Prefix:

Your existing pswp_prod_* or pswp_demo_* keys will continue to work! The system supports both formats.

If You Want to Switch to UUID:

1. New purchases will use UUID format automatically
2. Existing keys remain valid
3. No migration needed - both formats work simultaneously

---

✅ Format Validation Examples

Valid Keys:

// UUID format (Lemon Squeezy default)
'12345678-1234-1234-1234-123456789ABC' ✅
'ABCDEF12-3456-7890-ABCD-EF1234567890' ✅

// Custom prefix format
'pswp_prod_abc123def456' ✅
'pswp_demo_test1234' ✅
'pswp_dev_quicktest' ✅

Invalid Keys:

// Too short
'12345' ❌

// Wrong format
'license-key-12345' ❌

// Missing parts
'pswp_' ❌
'prod_abc123' ❌

// Wrong UUID format
'123-456-789' ❌

---

🧪 Testing License Keys

Test UUID Format:

# Valid UUID
curl -X POST http://localhost:4001/api/license/validate \
  -H 'Content-Type: application/json' \
  -d '{"licenseKey":"12345678-1234-1234-1234-123456789ABC"}'

# Response: {"valid":true,"status":"active"}

Test Custom Prefix Format:

# Valid pswp_ format
curl -X POST http://localhost:4001/api/license/validate \
  -H 'Content-Type: application/json' \
  -d '{"licenseKey":"pswp_demo_test1234"}'

# Response: {"valid":true,"status":"active"}

---

📊 Format Comparison

Feature	UUID Format	Custom Prefix
Setup Complexity	✅ None needed	⚠️ Requires config
Lemon Squeezy Default	✅ Yes	❌ No
Validation Support	✅ Full	✅ Full
Customer Experience	✅ Simple	✅ Simple
Recommended	✅ Yes	⚠️ Optional

---

🎯 Summary

What You Need to Know:

1. UUID format is the default - no configuration needed
2. Both formats are fully supported - choose what works for you
3. Use UUID format for simplicity - it's the Lemon Squeezy default
4. Custom prefix is optional - only if you need branding

Quick Decision:

Q: "Which format should I use?"
A: UUID format (Lemon Squeezy default) - it's simpler and requires no setup!

Q: "Will my pswpprod keys still work?"
A: Yes! The system supports both formats simultaneously.

Q: "Can I change formats later?"
A: Yes! Both work at the same time, no migration needed.

---

✅ Bottom Line: Use UUID format for the easiest setup experience!