spaps-mcp 0.1.0

package/dist/wizard/step-09-admin.md

@@ -0,0 +1,579 @@
+# SPAPS Integration Step 9/12: Admin Operations
+
+## Prerequisites Check
+
+Before starting, confirm you have completed:
+- ✅ Step 1-8: Full authentication, payments, and whitelist
+- ✅ Admin credentials configured in environment
+- ✅ Understanding of JWT authentication
+
+## Required TodoWrite List
+
+Create a TodoWrite with EXACTLY these items:
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Create admin panel component", status: "pending", activeForm: "Creating admin panel" },
+    { content: "Implement admin authentication first", status: "pending", activeForm: "Implementing admin auth" },
+    { content: "Use JWT for all admin API calls", status: "pending", activeForm: "Using JWT for API calls" },
+    { content: "Implement product sync endpoint", status: "pending", activeForm: "Implementing product sync" },
+    { content: "Add user management operations", status: "pending", activeForm: "Adding user management" },
+    { content: "Create admin statistics view", status: "pending", activeForm: "Creating statistics view" },
+    { content: "Add proper error handling for 403", status: "pending", activeForm: "Adding authorization errors" },
+    { content: "Request step 10 of SPAPS integration wizard", status: "pending", activeForm: "Requesting next step" }
+  ]
+})
+```
+
+## Admin Authentication Pattern
+
+⚠️ **CRITICAL**: Admin operations are NOT in the SDK. You must:
+1. Authenticate as admin using `signInWithPassword`
+2. Get the JWT token from the response
+3. Use that token for all admin API calls
+
+## Implementation Guide
+
+### 1. Admin Service
+
+Create a service for admin operations:
+
+```typescript
+// lib/admin-service.ts
+import { sdk } from './spaps'
+
+interface AdminAuth {
+  access_token: string
+  refresh_token: string
+  expires_in: number
+}
+
+class AdminService {
+  private adminToken: string | null = null
+  private tokenExpiry: number = 0
+
+  /**
+   * Authenticate as admin and store token
+   */
+  async authenticate(): Promise<void> {
+    // Check if we have a valid token
+    if (this.adminToken && Date.now() < this.tokenExpiry) {
+      return
+    }
+
+    const email = process.env.NEXT_PUBLIC_ADMIN_EMAIL
+    const password = process.env.NEXT_PUBLIC_ADMIN_PASSWORD
+
+    if (!email || !password) {
+      throw new Error('Admin credentials not configured')
+    }
+
+    try {
+      // Authenticate using SDK
+      const auth = await sdk.auth.signInWithPassword({
+        email,
+        password
+      })
+
+      this.adminToken = auth.access_token
+      this.tokenExpiry = Date.now() + (auth.expires_in * 1000)
+    } catch (error) {
+      console.error('Admin authentication failed:', error)
+      throw new Error('Failed to authenticate as admin')
+    }
+  }
+
+  /**
+   * Get admin headers for API calls
+   */
+  async getHeaders(): Promise<HeadersInit> {
+    await this.authenticate()
+    
+    return {
+      'Authorization': `Bearer ${this.adminToken}`,
+      'Content-Type': 'application/json',
+      'X-API-Key': process.env.SPAPS_API_KEY || 'test_key_local_dev_only'
+    }
+  }
+
+  /**
+   * Make authenticated admin API call
+   */
+  async apiCall<T>(
+    endpoint: string, 
+    options: RequestInit = {}
+  ): Promise<T> {
+    const headers = await this.getHeaders()
+    const apiUrl = process.env.NEXT_PUBLIC_SPAPS_API_URL || 'http://localhost:3301'
+    
+    const response = await fetch(`${apiUrl}${endpoint}`, {
+      ...options,
+      headers: {
+        ...headers,
+        ...(options.headers || {})
+      }
+    })
+
+    if (response.status === 403) {
+      throw new Error('Admin privileges required')
+    }
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}))
+      throw new Error(error.message || `API call failed: ${response.status}`)
+    }
+
+    return response.json()
+  }
+
+  /**
+   * Sync products from Stripe
+   */
+  async syncProducts(): Promise<any> {
+    return this.apiCall('/api/v1/admin/products/sync', {
+      method: 'POST'
+    })
+  }
+
+  /**
+   * Get admin statistics
+   */
+  async getStats(): Promise<any> {
+    return this.apiCall('/api/v1/admin/stats')
+  }
+
+  /**
+   * List all users
+   */
+  async listUsers(params?: {
+    limit?: number
+    offset?: number
+    search?: string
+  }): Promise<any> {
+    const queryParams = new URLSearchParams()
+    if (params?.limit) queryParams.append('limit', params.limit.toString())
+    if (params?.offset) queryParams.append('offset', params.offset.toString())
+    if (params?.search) queryParams.append('search', params.search)
+    
+    return this.apiCall(`/api/v1/admin/users?${queryParams}`)
+  }
+
+  /**
+   * Update user status
+   */
+  async updateUserStatus(
+    userId: string, 
+    status: 'active' | 'suspended' | 'deleted'
+  ): Promise<any> {
+    return this.apiCall(`/api/v1/admin/users/${userId}/status`, {
+      method: 'PUT',
+      body: JSON.stringify({ status })
+    })
+  }
+
+  /**
+   * Get audit logs
+   */
+  async getAuditLogs(params?: {
+    limit?: number
+    offset?: number
+    userId?: string
+    action?: string
+  }): Promise<any> {
+    const queryParams = new URLSearchParams()
+    if (params?.limit) queryParams.append('limit', params.limit.toString())
+    if (params?.offset) queryParams.append('offset', params.offset.toString())
+    if (params?.userId) queryParams.append('user_id', params.userId)
+    if (params?.action) queryParams.append('action', params.action)
+    
+    return this.apiCall(`/api/v1/admin/audit-logs?${queryParams}`)
+  }
+}
+
+export const adminService = new AdminService()
+```
+
+### 2. Admin Panel Component
+
+```typescript
+// components/admin/admin-panel.tsx
+'use client'
+
+import { useState, useEffect } from 'react'
+import { Button } from "@/components/ui/button"
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
+import { Badge } from "@/components/ui/badge"
+import { toast } from "sonner"
+import { adminService } from '@/lib/admin-service'
+import { 
+  Users, 
+  Package, 
+  Activity, 
+  Shield, 
+  RefreshCw,
+  Loader2,
+  AlertTriangle 
+} from 'lucide-react'
+
+interface Stats {
+  users: {
+    total: number
+    active: number
+    new_today: number
+  }
+  payments: {
+    revenue_month: number
+    active_subscriptions: number
+    failed_payments: number
+  }
+  system: {
+    api_calls_today: number
+    error_rate: number
+    uptime: string
+  }
+}
+
+export function AdminPanel() {
+  const [isLoading, setIsLoading] = useState(false)
+  const [stats, setStats] = useState<Stats | null>(null)
+  const [users, setUsers] = useState<any[]>([])
+  const [isAdmin, setIsAdmin] = useState<boolean | null>(null)
+
+  useEffect(() => {
+    checkAdminAccess()
+  }, [])
+
+  const checkAdminAccess = async () => {
+    try {
+      await adminService.authenticate()
+      setIsAdmin(true)
+      loadStats()
+    } catch (error) {
+      setIsAdmin(false)
+      toast.error('Admin access denied')
+    }
+  }
+
+  const loadStats = async () => {
+    try {
+      setIsLoading(true)
+      const data = await adminService.getStats()
+      setStats(data)
+    } catch (error: any) {
+      toast.error(`Failed to load stats: ${error.message}`)
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const syncProducts = async () => {
+    setIsLoading(true)
+    try {
+      const result = await adminService.syncProducts()
+      toast.success(`Synced ${result.synced_count} products from Stripe`)
+    } catch (error: any) {
+      if (error.message.includes('403')) {
+        toast.error('Admin privileges required')
+      } else {
+        toast.error(`Sync failed: ${error.message}`)
+      }
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const loadUsers = async () => {
+    setIsLoading(true)
+    try {
+      const data = await adminService.listUsers({ limit: 10 })
+      setUsers(data.users || [])
+    } catch (error: any) {
+      toast.error(`Failed to load users: ${error.message}`)
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  if (isAdmin === false) {
+    return (
+      <Card className="w-full max-w-2xl">
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2 text-red-600">
+            <AlertTriangle className="h-5 w-5" />
+            Admin Access Required
+          </CardTitle>
+          <CardDescription>
+            You must be authenticated as an admin to access this panel
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <p className="text-sm text-muted-foreground">
+            Please ensure you have admin credentials configured and try again.
+          </p>
+        </CardContent>
+      </Card>
+    )
+  }
+
+  if (isAdmin === null) {
+    return (
+      <Card className="w-full max-w-2xl">
+        <CardContent className="flex justify-center py-8">
+          <Loader2 className="h-8 w-8 animate-spin" />
+        </CardContent>
+      </Card>
+    )
+  }
+
+  return (
+    <div className="w-full max-w-4xl space-y-6">
+      {/* Stats Overview */}
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-sm font-medium flex items-center gap-2">
+              <Users className="h-4 w-4" />
+              Total Users
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <p className="text-2xl font-bold">{stats?.users.total || 0}</p>
+            <p className="text-xs text-muted-foreground">
+              +{stats?.users.new_today || 0} today
+            </p>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-sm font-medium flex items-center gap-2">
+              <Package className="h-4 w-4" />
+              Active Subscriptions
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <p className="text-2xl font-bold">
+              {stats?.payments.active_subscriptions || 0}
+            </p>
+            <p className="text-xs text-muted-foreground">
+              ${(stats?.payments.revenue_month || 0) / 100}/mo
+            </p>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-sm font-medium flex items-center gap-2">
+              <Activity className="h-4 w-4" />
+              API Calls Today
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <p className="text-2xl font-bold">
+              {stats?.system.api_calls_today || 0}
+            </p>
+            <p className="text-xs text-muted-foreground">
+              {stats?.system.error_rate || 0}% error rate
+            </p>
+          </CardContent>
+        </Card>
+      </div>
+
+      {/* Admin Actions */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <Shield className="h-5 w-5" />
+            Admin Actions
+          </CardTitle>
+          <CardDescription>
+            Manage system operations and sync data
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Tabs defaultValue="products">
+            <TabsList>
+              <TabsTrigger value="products">Products</TabsTrigger>
+              <TabsTrigger value="users">Users</TabsTrigger>
+              <TabsTrigger value="system">System</TabsTrigger>
+            </TabsList>
+
+            <TabsContent value="products" className="space-y-4">
+              <div>
+                <h4 className="text-sm font-medium mb-2">Stripe Sync</h4>
+                <p className="text-xs text-muted-foreground mb-4">
+                  Sync products and prices from your Stripe account
+                </p>
+                <Button 
+                  onClick={syncProducts}
+                  disabled={isLoading}
+                >
+                  {isLoading ? (
+                    <>
+                      <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+                      Syncing...
+                    </>
+                  ) : (
+                    <>
+                      <RefreshCw className="mr-2 h-4 w-4" />
+                      Sync Products
+                    </>
+                  )}
+                </Button>
+              </div>
+            </TabsContent>
+
+            <TabsContent value="users" className="space-y-4">
+              <div>
+                <h4 className="text-sm font-medium mb-2">User Management</h4>
+                <Button 
+                  variant="outline"
+                  onClick={loadUsers}
+                  disabled={isLoading}
+                >
+                  Load Users
+                </Button>
+                {users.length > 0 && (
+                  <div className="mt-4 space-y-2">
+                    {users.map((user) => (
+                      <div key={user.id} className="flex items-center justify-between p-2 border rounded">
+                        <div>
+                          <p className="text-sm font-medium">{user.email}</p>
+                          <p className="text-xs text-muted-foreground">
+                            ID: {user.id}
+                          </p>
+                        </div>
+                        <Badge variant={user.status === 'active' ? 'default' : 'secondary'}>
+                          {user.status}
+                        </Badge>
+                      </div>
+                    ))}
+                  </div>
+                )}
+              </div>
+            </TabsContent>
+
+            <TabsContent value="system" className="space-y-4">
+              <div>
+                <h4 className="text-sm font-medium mb-2">System Status</h4>
+                <div className="space-y-2">
+                  <div className="flex justify-between text-sm">
+                    <span>Uptime</span>
+                    <span className="font-mono">{stats?.system.uptime || 'N/A'}</span>
+                  </div>
+                  <div className="flex justify-between text-sm">
+                    <span>Error Rate</span>
+                    <span className="font-mono">{stats?.system.error_rate || 0}%</span>
+                  </div>
+                </div>
+              </div>
+            </TabsContent>
+          </Tabs>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}
+```
+
+## Available Admin Endpoints
+
+These require admin JWT authentication:
+
+```typescript
+// Products
+POST   /api/v1/admin/products/sync
+PUT    /api/v1/admin/products/:id
+DELETE /api/v1/admin/products/:id
+
+// Users
+GET    /api/v1/admin/users
+PUT    /api/v1/admin/users/:id/status
+DELETE /api/v1/admin/users/:id
+
+// Statistics
+GET    /api/v1/admin/stats
+GET    /api/v1/admin/audit-logs
+
+// System
+POST   /api/v1/admin/cache/clear
+GET    /api/v1/admin/health
+```
+
+## Validation Checklist
+
+✅ **Authentication**:
+- Admin credentials in environment
+- JWT token obtained via signInWithPassword
+- Token used in Authorization header
+
+✅ **API Calls**:
+- All admin endpoints use JWT
+- Handle 403 Forbidden errors
+- Show appropriate error messages
+
+✅ **Implementation**:
+- Admin service handles authentication
+- Panel shows statistics
+- Product sync works
+- User management available
+
+## Common Mistakes to Avoid
+
+❌ **Looking for admin methods in SDK**:
+```typescript
+// WRONG - These don't exist
+sdk.admin.syncProducts()
+sdk.admin.getStats()
+```
+
+❌ **Using regular user token**:
+```typescript
+// WRONG - Must be admin token
+const token = TokenManager.getAccessToken() // User token won't work
+```
+
+❌ **Not handling 403 errors**:
+```typescript
+// WRONG - No error handling
+const response = await fetch('/api/v1/admin/stats')
+// Will fail with 403 if not admin
+```
+
+## Testing Admin Operations
+
+1. **Check Admin Auth**:
+   - Use admin@example.com / Admin123!
+   - Should authenticate successfully
+
+2. **Test Product Sync**:
+   - Click "Sync Products"
+   - Should sync from Stripe
+
+3. **Test Authorization**:
+   - Try with non-admin user
+   - Should show "Admin Access Required"
+
+## Next Step
+
+When ALL todos are ✅ complete and admin panel works:
+
+```javascript
+mcp__product-manager__get_agent_instructions({
+  category: "spaps-integration",
+  project: "spaps-demo",
+  step: 10
+})
+```
+
+## Summary
+
+Admin operations provide:
+- **Full system control** - Manage users and products
+- **Statistics dashboard** - Monitor system health
+- **Stripe synchronization** - Keep products in sync
+- **Audit logging** - Track all admin actions
+
+Remember: Always authenticate as admin first!