feat: Add Stripe Customer Portal for API Key Recovery

- Add POST /v1/billing/portal endpoint for customer portal access
- Add GET /v1/billing/recover endpoint for API key recovery
- Implement getKeyByEmail() and getCustomerIdByEmail() service functions
- Add comprehensive test coverage for new endpoints and services
- Create dedicated recovery page at /recovery.html with forms
- Add 'Lost your API key?' link on landing page near pricing
- Update OpenAPI documentation for new endpoints
- Return masked API keys for security (snap_xxxx...xxxx format)
- Log full keys for manual email sending (email service TBD)
- Include proper error handling and input validation

src/services/__tests__/keys.test.ts

@@ -1,5 +1,12 @@
-import { describe, it, expect } from 'vitest'
-import { getTierLimit } from '../keys.js'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { getTierLimit, getKeyByEmail, getCustomerIdByEmail } from '../keys.js'
+
+// Mock the db module
+vi.mock('../db.js', () => ({
+  queryWithRetry: vi.fn()
+}))
+
+import { queryWithRetry } from '../db.js'
 
 describe('getTierLimit', () => {
   it('should return 100 for free tier', () => {
@@ -26,3 +33,94 @@ describe('getTierLimit', () => {
     expect(getTierLimit('')).toBe(100)
   })
 })
+
+describe('getKeyByEmail', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should return key info when email exists', async () => {
+    const mockRow = {
+      key: 'snap_abcd1234efgh5678',
+      tier: 'pro',
+      email: 'user@example.com',
+      created_at: '2024-01-01T00:00:00Z',
+      stripe_customer_id: 'cus_123456'
+    }
+
+    vi.mocked(queryWithRetry).mockResolvedValue({
+      rows: [mockRow]
+    })
+
+    const result = await getKeyByEmail('user@example.com')
+    
+    expect(result).toEqual({
+      key: 'snap_abcd1234efgh5678',
+      tier: 'pro',
+      email: 'user@example.com',
+      createdAt: '2024-01-01T00:00:00Z',
+      stripeCustomerId: 'cus_123456'
+    })
+    
+    expect(queryWithRetry).toHaveBeenCalledWith(
+      'SELECT key, tier, email, created_at, stripe_customer_id FROM api_keys WHERE email = $1',
+      ['user@example.com']
+    )
+  })
+
+  it('should return undefined when email does not exist', async () => {
+    vi.mocked(queryWithRetry).mockResolvedValue({
+      rows: []
+    })
+
+    const result = await getKeyByEmail('nonexistent@example.com')
+    
+    expect(result).toBeUndefined()
+  })
+
+  it('should handle database errors gracefully', async () => {
+    vi.mocked(queryWithRetry).mockRejectedValue(new Error('Database error'))
+
+    const result = await getKeyByEmail('user@example.com')
+    
+    expect(result).toBeUndefined()
+  })
+})
+
+describe('getCustomerIdByEmail', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should return customer ID when email exists and has stripe customer', async () => {
+    vi.mocked(queryWithRetry).mockResolvedValue({
+      rows: [{ stripe_customer_id: 'cus_123456' }]
+    })
+
+    const result = await getCustomerIdByEmail('user@example.com')
+    
+    expect(result).toBe('cus_123456')
+    expect(queryWithRetry).toHaveBeenCalledWith(
+      'SELECT stripe_customer_id FROM api_keys WHERE email = $1 AND stripe_customer_id IS NOT NULL',
+      ['user@example.com']
+    )
+  })
+
+  it('should return undefined when email does not exist', async () => {
+    vi.mocked(queryWithRetry).mockResolvedValue({
+      rows: []
+    })
+
+    const result = await getCustomerIdByEmail('nonexistent@example.com')
+    
+    expect(result).toBeUndefined()
+  })
+
+  it('should handle database errors gracefully', async () => {
+    vi.mocked(queryWithRetry).mockRejectedValue(new Error('Database error'))
+
+    const result = await getCustomerIdByEmail('user@example.com')
+    
+    expect(result).toBeUndefined()
+  })
+})

src/services/keys.ts

@@ -205,3 +205,39 @@ export async function updateEmailByCustomer(customerId: string, newEmail: string
     if (k.stripeCustomerId === customerId) k.email = newEmail;
   }
 }
+
+export async function getKeyByEmail(email: string): Promise<ApiKey | undefined> {
+  try {
+    const result = await queryWithRetry(
+      "SELECT key, tier, email, created_at, stripe_customer_id FROM api_keys WHERE email = $1",
+      [email]
+    );
+    if (result.rows.length === 0) return undefined;
+    
+    const r = result.rows[0];
+    return {
+      key: r.key,
+      tier: r.tier,
+      email: r.email,
+      createdAt: r.created_at instanceof Date ? r.created_at.toISOString() : r.created_at,
+      stripeCustomerId: r.stripe_customer_id || undefined,
+    };
+  } catch (err) {
+    logger.error({ err }, "Failed to get key by email");
+    return undefined;
+  }
+}
+
+export async function getCustomerIdByEmail(email: string): Promise<string | undefined> {
+  try {
+    const result = await queryWithRetry(
+      "SELECT stripe_customer_id FROM api_keys WHERE email = $1 AND stripe_customer_id IS NOT NULL",
+      [email]
+    );
+    if (result.rows.length === 0) return undefined;
+    return result.rows[0].stripe_customer_id;
+  } catch (err) {
+    logger.error({ err }, "Failed to get customer ID by email");
+    return undefined;
+  }
+}