spaps-mcp 0.1.0

package/dist/wizard/step-08-whitelist.md

@@ -0,0 +1,338 @@
+# SPAPS Integration Step 8/12: Whitelist Operations
+
+## Prerequisites Check
+
+Before starting, confirm you have completed:
+- ✅ Step 1-7: Full authentication and payment implementation
+- ✅ Have admin credentials ready
+- ✅ Understanding that whitelist is NOT in the main SDK
+
+## Required TodoWrite List
+
+Create a TodoWrite with EXACTLY these items:
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Create whitelist checker component", status: "pending", activeForm: "Creating whitelist checker component" },
+    { content: "Note that whitelist is NOT in main SDK", status: "pending", activeForm: "Noting whitelist is not in SDK" },
+    { content: "Choose implementation approach (Direct API or WhitelistManager)", status: "pending", activeForm: "Choosing implementation approach" },
+    { content: "Implement admin authentication pattern", status: "pending", activeForm: "Implementing admin authentication" },
+    { content: "Add whitelist check functionality", status: "pending", activeForm: "Adding whitelist check" },
+    { content: "Test with vip@example.com", status: "pending", activeForm: "Testing whitelist check" },
+    { content: "Handle authorization errors", status: "pending", activeForm: "Handling authorization errors" },
+    { content: "Request step 9 of SPAPS integration wizard", status: "pending", activeForm: "Requesting next step" }
+  ]
+})
+```
+
+## Important Context
+
+⚠️ **CRITICAL**: The whitelist functionality is NOT in the main SDK exports!
+
+You have **TWO OPTIONS** for implementation:
+
+### Option 1: Direct API Calls (Recommended for Learning)
+Make direct HTTP requests to the whitelist endpoints with admin JWT token.
+
+### Option 2: WhitelistManager Utility (Advanced)
+Use the `WhitelistManager` class from `spaps-sdk/admin-utils` (separate import).
+
+## Implementation Options
+
+### Option 1: Direct API Calls (Recommended)
+
+This approach helps you understand the underlying API structure:
+
+```typescript
+// components/admin/whitelist-checker.tsx
+'use client'
+
+import { useState } from 'react'
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
+import { toast } from "sonner"
+import { sdk } from '@/lib/spaps'
+import { TokenManager } from 'spaps-sdk'
+
+export function WhitelistChecker() {
+  const [email, setEmail] = useState('')
+  const [isLoading, setIsLoading] = useState(false)
+  const [result, setResult] = useState<any>(null)
+
+  const checkWhitelist = async () => {
+    setIsLoading(true)
+    try {
+      // Step 1: Authenticate as admin first
+      const adminAuth = await sdk.auth.signInWithPassword({
+        email: process.env.NEXT_PUBLIC_ADMIN_EMAIL || 'admin@example.com',
+        password: process.env.NEXT_PUBLIC_ADMIN_PASSWORD || 'Admin123!'
+      })
+
+      // Step 2: Make direct API call with admin JWT
+      const response = await fetch(
+        `${process.env.NEXT_PUBLIC_SPAPS_API_URL}/api/v1/whitelist/check?email=${encodeURIComponent(email)}`,
+        {
+          headers: {
+            'Authorization': `Bearer ${adminAuth.access_token}`,
+            'X-API-Key': process.env.NEXT_PUBLIC_SPAPS_API_KEY || 'test_key_local_dev_only',
+            'Content-Type': 'application/json'
+          }
+        }
+      )
+
+      if (!response.ok) {
+        if (response.status === 403) {
+          throw new Error('Admin privileges required')
+        }
+        throw new Error(`HTTP ${response.status}`)
+      }
+
+      const data = await response.json()
+      setResult(data)
+      
+      if (data.isWhitelisted) {
+        toast.success(`✅ ${email} is whitelisted!`)
+      } else {
+        toast.info(`❌ ${email} is not whitelisted`)
+      }
+    } catch (error: any) {
+      toast.error(`Failed: ${error.message}`)
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  // ... rest of component
+}
+```
+
+### Option 2: WhitelistManager Utility (Advanced)
+
+This approach uses the built-in utility class for cleaner code:
+
+```typescript
+// lib/admin-utils.ts
+import { WhitelistManager } from 'spaps-sdk/admin-utils'
+import { sdk } from './spaps'
+
+let whitelistManager: WhitelistManager | null = null
+
+export async function getWhitelistManager() {
+  if (whitelistManager) return whitelistManager
+  
+  // Authenticate as admin
+  const adminAuth = await sdk.auth.signInWithPassword({
+    email: process.env.NEXT_PUBLIC_ADMIN_EMAIL!,
+    password: process.env.NEXT_PUBLIC_ADMIN_PASSWORD!
+  })
+  
+  // Create WhitelistManager instance
+  whitelistManager = new WhitelistManager({
+    apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL || 'http://localhost:3301',
+    apiKey: process.env.NEXT_PUBLIC_SPAPS_API_KEY || 'test_key_local_dev_only',
+    adminToken: adminAuth.access_token
+  })
+  
+  return whitelistManager
+}
+
+// components/admin/whitelist-checker.tsx
+import { getWhitelistManager } from '@/lib/admin-utils'
+
+export function WhitelistChecker() {
+  const checkWhitelist = async () => {
+    try {
+      const manager = await getWhitelistManager()
+      
+      // Check if email is whitelisted
+      const entry = await manager.check(email)
+      
+      if (entry) {
+        toast.success(`✅ ${email} is whitelisted (Tier: ${entry.tier})`)
+        setResult(entry)
+      } else {
+        toast.info(`❌ ${email} is not whitelisted`)
+        setResult({ isWhitelisted: false })
+      }
+    } catch (error: any) {
+      toast.error(`Failed: ${error.message}`)
+    }
+  }
+  
+  // Additional operations available with WhitelistManager:
+  const addToWhitelist = async () => {
+    const manager = await getWhitelistManager()
+    await manager.add(email, 'premium', { bypass_payment: true })
+  }
+  
+  const removeFromWhitelist = async () => {
+    const manager = await getWhitelistManager()
+    await manager.remove(email)
+  }
+  
+  const getStats = async () => {
+    const manager = await getWhitelistManager()
+    const stats = await manager.getStats()
+    console.log('Whitelist stats:', stats)
+  }
+}
+```
+
+## Available WhitelistManager Methods
+
+If using Option 2, these methods are available:
+
+```typescript
+interface WhitelistManager {
+  check(email: string): Promise<WhitelistEntry | null>
+  add(email: string, tier: 'basic' | 'premium' | 'enterprise', options?: {...}): Promise<WhitelistEntry>
+  bulkAdd(emails: Array<{email: string, tier?: string}>): Promise<BulkResult>
+  list(options?: {limit?: number, offset?: number, tier?: string}): Promise<WhitelistList>
+  update(email: string, updates: {...}): Promise<WhitelistEntry>
+  remove(email: string): Promise<void>
+  getStats(): Promise<WhitelistStats>
+  clearAll(): Promise<number> // Use with caution!
+}
+```
+
+## Admin Operations Beyond Whitelist
+
+You can also perform other admin operations:
+
+```typescript
+// Product sync
+const syncProducts = async () => {
+  const adminAuth = await sdk.auth.signInWithPassword({
+    email: 'admin@example.com',
+    password: 'Admin123!'
+  })
+  
+  const response = await fetch(
+    `${process.env.NEXT_PUBLIC_SPAPS_API_URL}/api/v1/admin/products/sync`,
+    {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${adminAuth.access_token}`,
+        'X-API-Key': process.env.NEXT_PUBLIC_SPAPS_API_KEY,
+        'Content-Type': 'application/json'
+      }
+    }
+  )
+  
+  return response.json()
+}
+```
+
+## Validation Checklist
+
+✅ **Implementation Choice**:
+- Decided between Direct API or WhitelistManager approach
+- Understand pros/cons of each approach
+
+✅ **Authentication**:
+- Admin credentials stored securely (environment variables)
+- Admin authentication implemented before whitelist calls
+- JWT token properly passed in Authorization header
+
+✅ **Error Handling**:
+- Handle 403 Forbidden (not admin)
+- Handle 401 Unauthorized (invalid token)
+- Handle network errors
+- Show user-friendly error messages
+
+✅ **Testing**:
+- Test with `vip@example.com` (should be whitelisted in local mode)
+- Test with random email (should not be whitelisted)
+- Test without admin auth (should fail with 403)
+
+## Common Mistakes to Avoid
+
+❌ **Looking for whitelist in main SDK**: 
+```javascript
+// WRONG - This doesn't exist!
+sdk.whitelist.check(email)
+sdk.admin.whitelist.add(email)
+```
+
+❌ **Not authenticating as admin first**:
+```javascript
+// WRONG - Missing admin auth
+fetch('/api/v1/whitelist/check', {
+  headers: { 'X-API-Key': apiKey } // Missing JWT!
+})
+```
+
+❌ **Using regular user token**:
+```javascript
+// WRONG - Must be admin token
+const userToken = TokenManager.getAccessToken() // Regular user token won't work
+```
+
+✅ **CORRECT - Always authenticate as admin**:
+```javascript
+const adminAuth = await sdk.auth.signInWithPassword({
+  email: 'admin@example.com',
+  password: 'Admin123!'
+})
+// Now use adminAuth.access_token for whitelist operations
+```
+
+## Testing Requirements
+
+1. **Successful Whitelist Check**:
+   - Email: `vip@example.com`
+   - Should return: `{ isWhitelisted: true, tier: 'premium' }`
+
+2. **Non-whitelisted Email**:
+   - Email: `regular@example.com`
+   - Should return: `{ isWhitelisted: false }`
+
+3. **Authorization Failure**:
+   - Use non-admin credentials
+   - Should get 403 Forbidden error
+
+## Troubleshooting
+
+If whitelist operations fail:
+
+1. **Check Admin Credentials**:
+   ```bash
+   # Test admin login
+   curl -X POST http://localhost:3301/api/auth/login \
+     -H "Content-Type: application/json" \
+     -d '{"email":"admin@example.com","password":"Admin123!"}'
+   ```
+
+2. **Verify JWT Token**:
+   ```javascript
+   console.log('Admin token:', adminAuth.access_token)
+   // Should be a long JWT string
+   ```
+
+3. **Check API Endpoint**:
+   ```javascript
+   console.log('Whitelist URL:', `${process.env.NEXT_PUBLIC_SPAPS_API_URL}/api/v1/whitelist/check`)
+   // Should be: http://localhost:3301/api/v1/whitelist/check
+   ```
+
+## Next Step
+
+When ALL todos are ✅ complete and whitelist checking works:
+
+```javascript
+mcp__product-manager__get_agent_instructions({
+  category: "spaps-integration",
+  project: "spaps-demo",
+  step: 9
+})
+```
+
+## Summary
+
+Whitelist operations require admin privileges and are NOT in the main SDK. You can either:
+1. **Direct API calls** - More control, better for learning
+2. **WhitelistManager utility** - Cleaner code, more features
+
+Both approaches work perfectly - choose based on your needs!