spaps-mcp 0.1.0

package/dist/wizard/step-10-errors.md

@@ -0,0 +1,525 @@
+# SPAPS Integration Step 10/12: Error Handling & Token Management
+
+## Prerequisites Check
+
+Before starting, confirm you have completed:
+- ✅ Step 1-9: Full implementation with auth, payments, admin
+- ✅ TokenManager being used for storage
+- ✅ Basic error handling in place
+
+## Required TodoWrite List
+
+Create a TodoWrite with EXACTLY these items:
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Import SweetPotatoAPIError from spaps-sdk", status: "pending", activeForm: "Importing error class" },
+    { content: "Create centralized error handler", status: "pending", activeForm: "Creating error handler" },
+    { content: "Add specific error code handling", status: "pending", activeForm: "Adding error code handling" },
+    { content: "Implement TokenManager.isTokenExpired checks", status: "pending", activeForm: "Implementing token expiry checks" },
+    { content: "Setup auto-refresh properly", status: "pending", activeForm: "Setting up auto-refresh" },
+    { content: "Add toast notifications for all errors", status: "pending", activeForm: "Adding toast notifications" },
+    { content: "Create error boundary component", status: "pending", activeForm: "Creating error boundary" },
+    { content: "Request step 11 of SPAPS integration wizard", status: "pending", activeForm: "Requesting next step" }
+  ]
+})
+```
+
+## Comprehensive Error Handling
+
+### 1. Centralized Error Handler
+
+Create a unified error handling utility:
+
+```typescript
+// lib/error-handler.ts
+import { SweetPotatoAPIError } from 'spaps-sdk'
+import { toast } from 'sonner'
+
+export interface ErrorContext {
+  operation?: string
+  userId?: string
+  details?: any
+}
+
+export class ErrorHandler {
+  private static errorCounts: Map<string, number> = new Map()
+  private static readonly MAX_ERRORS_BEFORE_RELOAD = 5
+
+  /**
+   * Handle any error with appropriate user feedback
+   */
+  static handle(error: any, context?: ErrorContext): void {
+    console.error(`Error in ${context?.operation || 'unknown operation'}:`, error)
+
+    if (error instanceof SweetPotatoAPIError) {
+      this.handleAPIError(error, context)
+    } else if (error?.code) {
+      this.handleCodedError(error, context)
+    } else if (error?.message) {
+      this.handleGenericError(error, context)
+    } else {
+      this.handleUnknownError(error, context)
+    }
+
+    // Track error frequency
+    this.trackError(error)
+  }
+
+  /**
+   * Handle SweetPotatoAPIError specifically
+   */
+  private static handleAPIError(error: SweetPotatoAPIError, context?: ErrorContext): void {
+    const errorMessages: Record<string, string> = {
+      // Authentication Errors
+      'INVALID_CREDENTIALS': 'Invalid email or password',
+      'USER_NOT_FOUND': 'No account found with these credentials',
+      'EMAIL_NOT_VERIFIED': 'Please verify your email before signing in',
+      'ACCOUNT_SUSPENDED': 'Your account has been suspended',
+      'ACCOUNT_DELETED': 'This account no longer exists',
+      
+      // Authorization Errors
+      'UNAUTHORIZED': 'You must be logged in to do that',
+      'FORBIDDEN': 'You don\'t have permission to do that',
+      'INSUFFICIENT_PERMISSIONS': 'Additional permissions required',
+      'ADMIN_ONLY': 'Admin access required',
+      
+      // Token Errors
+      'TOKEN_EXPIRED': 'Your session has expired. Please sign in again.',
+      'TOKEN_INVALID': 'Invalid authentication token',
+      'TOKEN_REVOKED': 'Your session has been revoked',
+      'REFRESH_TOKEN_EXPIRED': 'Please sign in again to continue',
+      
+      // Rate Limiting
+      'RATE_LIMITED': 'Too many requests. Please slow down.',
+      'QUOTA_EXCEEDED': 'You\'ve exceeded your usage quota',
+      
+      // Payment Errors
+      'PAYMENT_REQUIRED': 'Payment required to continue',
+      'CARD_DECLINED': 'Your card was declined',
+      'INSUFFICIENT_FUNDS': 'Insufficient funds for this transaction',
+      'SUBSCRIPTION_EXPIRED': 'Your subscription has expired',
+      'PAYMENT_FAILED': 'Payment processing failed',
+      
+      // Wallet Errors
+      'INVALID_SIGNATURE': 'Invalid wallet signature',
+      'WALLET_NOT_FOUND': 'Wallet not registered',
+      'WALLET_ALREADY_LINKED': 'This wallet is already linked to another account',
+      'CHAIN_NOT_SUPPORTED': 'This blockchain is not supported',
+      
+      // Validation Errors
+      'INVALID_EMAIL': 'Please enter a valid email address',
+      'INVALID_PASSWORD': 'Password must be at least 8 characters',
+      'INVALID_INPUT': 'Please check your input and try again',
+      'MISSING_REQUIRED_FIELD': 'Please fill in all required fields',
+      
+      // Server Errors
+      'INTERNAL_ERROR': 'Something went wrong. Please try again.',
+      'SERVICE_UNAVAILABLE': 'Service temporarily unavailable',
+      'NETWORK_ERROR': 'Network connection failed',
+      'DATABASE_ERROR': 'Database operation failed',
+      
+      // Business Logic Errors
+      'DUPLICATE_ENTRY': 'This already exists',
+      'NOT_FOUND': 'The requested item was not found',
+      'CONFLICT': 'This conflicts with existing data',
+      'PRECONDITION_FAILED': 'Preconditions not met'
+    }
+
+    const message = errorMessages[error.code || ''] || error.message || 'An error occurred'
+    
+    // Show toast based on error severity
+    if (error.status && error.status >= 500) {
+      toast.error(message, {
+        description: 'Please try again later',
+        duration: 5000
+      })
+    } else if (error.code === 'TOKEN_EXPIRED') {
+      toast.error(message, {
+        action: {
+          label: 'Sign In',
+          onClick: () => window.location.href = '/auth'
+        }
+      })
+    } else {
+      toast.error(message)
+    }
+  }
+
+  /**
+   * Handle errors with codes (like MetaMask errors)
+   */
+  private static handleCodedError(error: any, context?: ErrorContext): void {
+    const walletErrors: Record<number, string> = {
+      4001: 'Transaction rejected by user',
+      4100: 'The requested account and/or method has not been authorized',
+      4200: 'The requested method is not supported',
+      4900: 'Provider is disconnected',
+      4901: 'Provider is disconnected from all chains',
+      '-32002': 'Request already pending in wallet',
+      '-32003': 'Transaction rejected',
+      '-32603': 'Internal wallet error'
+    }
+
+    const message = walletErrors[error.code] || error.message || 'Operation failed'
+    toast.error(message)
+  }
+
+  /**
+   * Handle generic errors with messages
+   */
+  private static handleGenericError(error: any, context?: ErrorContext): void {
+    toast.error(error.message || 'An unexpected error occurred')
+  }
+
+  /**
+   * Handle completely unknown errors
+   */
+  private static handleUnknownError(error: any, context?: ErrorContext): void {
+    toast.error('An unexpected error occurred. Please try again.')
+  }
+
+  /**
+   * Track error frequency and reload if too many
+   */
+  private static trackError(error: any): void {
+    const key = error?.code || error?.message || 'unknown'
+    const count = (this.errorCounts.get(key) || 0) + 1
+    this.errorCounts.set(key, count)
+
+    if (count >= this.MAX_ERRORS_BEFORE_RELOAD) {
+      toast.error('Multiple errors detected. Reloading page...', {
+        duration: 3000,
+        onAutoClose: () => window.location.reload()
+      })
+    }
+  }
+
+  /**
+   * Clear error tracking
+   */
+  static clearErrors(): void {
+    this.errorCounts.clear()
+  }
+}
+```
+
+### 2. Advanced Token Management
+
+Enhance token management with expiry checks:
+
+```typescript
+// lib/token-manager-enhanced.ts
+import { TokenManager, sdk } from '@/lib/spaps'
+
+export class TokenManagerEnhanced {
+  private static refreshPromise: Promise<boolean> | null = null
+  private static refreshInterval: NodeJS.Timeout | null = null
+
+  /**
+   * Initialize auto-refresh with proper cleanup
+   */
+  static startAutoRefresh(): void {
+    // Clear any existing interval
+    this.stopAutoRefresh()
+
+    // Check token every 5 minutes
+    this.refreshInterval = setInterval(() => {
+      this.checkAndRefreshToken()
+    }, 5 * 60 * 1000)
+
+    // Do initial check
+    this.checkAndRefreshToken()
+  }
+
+  /**
+   * Stop auto-refresh
+   */
+  static stopAutoRefresh(): void {
+    if (this.refreshInterval) {
+      clearInterval(this.refreshInterval)
+      this.refreshInterval = null
+    }
+  }
+
+  /**
+   * Check token expiry and refresh if needed
+   */
+  static async checkAndRefreshToken(): Promise<boolean> {
+    // Prevent multiple simultaneous refreshes
+    if (this.refreshPromise) {
+      return this.refreshPromise
+    }
+
+    const accessToken = TokenManager.getAccessToken()
+    if (!accessToken) {
+      return false
+    }
+
+    // Check if token will expire in next 10 minutes
+    const tokenExpired = TokenManager.isTokenExpired(accessToken)
+    const tokenExpiringInfo = this.isTokenExpiringSoon(accessToken, 10 * 60)
+
+    if (tokenExpired || tokenExpiringInfo.expiringSoon) {
+      console.log(`Token ${tokenExpired ? 'expired' : 'expiring soon'}, refreshing...`)
+      
+      this.refreshPromise = this.refreshToken()
+      const result = await this.refreshPromise
+      this.refreshPromise = null
+      
+      return result
+    }
+
+    return true
+  }
+
+  /**
+   * Refresh the token
+   */
+  private static async refreshToken(): Promise<boolean> {
+    const refreshToken = TokenManager.getRefreshToken()
+    if (!refreshToken) {
+      console.error('No refresh token available')
+      this.handleTokenRefreshFailure()
+      return false
+    }
+
+    try {
+      const newTokens = await sdk.auth.refreshToken(refreshToken)
+      TokenManager.storeTokens(newTokens)
+      console.log('Token refreshed successfully')
+      return true
+    } catch (error) {
+      console.error('Token refresh failed:', error)
+      this.handleTokenRefreshFailure()
+      return false
+    }
+  }
+
+  /**
+   * Check if token is expiring soon
+   */
+  private static isTokenExpiringSoon(
+    token: string, 
+    thresholdSeconds: number = 600
+  ): { expiringSoon: boolean; remainingSeconds?: number } {
+    try {
+      const parts = token.split('.')
+      if (parts.length !== 3) {
+        return { expiringSoon: true }
+      }
+
+      const payload = JSON.parse(atob(parts[1]))
+      const expirationTime = payload.exp * 1000
+      const currentTime = Date.now()
+      const remainingTime = expirationTime - currentTime
+      const remainingSeconds = Math.floor(remainingTime / 1000)
+
+      return {
+        expiringSoon: remainingSeconds < thresholdSeconds,
+        remainingSeconds
+      }
+    } catch {
+      return { expiringSoon: true }
+    }
+  }
+
+  /**
+   * Handle token refresh failure
+   */
+  private static handleTokenRefreshFailure(): void {
+    TokenManager.clearTokens()
+    this.stopAutoRefresh()
+    
+    // Redirect to login
+    if (typeof window !== 'undefined') {
+      window.location.href = '/auth?error=session_expired'
+    }
+  }
+}
+```
+
+### 3. React Error Boundary
+
+Create an error boundary for React components:
+
+```typescript
+// components/error-boundary.tsx
+'use client'
+
+import React, { Component, ReactNode } from 'react'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
+import { Button } from "@/components/ui/button"
+import { AlertTriangle } from 'lucide-react'
+
+interface Props {
+  children: ReactNode
+  fallback?: ReactNode
+}
+
+interface State {
+  hasError: boolean
+  error: Error | null
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props)
+    this.state = { hasError: false, error: null }
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error }
+  }
+
+  componentDidCatch(error: Error, errorInfo: any) {
+    console.error('Error boundary caught:', error, errorInfo)
+    
+    // Log to error reporting service
+    if (typeof window !== 'undefined') {
+      // Example: Send to Sentry, LogRocket, etc.
+      // window.Sentry?.captureException(error)
+    }
+  }
+
+  handleReset = () => {
+    this.setState({ hasError: false, error: null })
+  }
+
+  render() {
+    if (this.state.hasError) {
+      if (this.props.fallback) {
+        return this.props.fallback
+      }
+
+      return (
+        <div className="min-h-screen flex items-center justify-center p-4">
+          <Card className="w-full max-w-md">
+            <CardHeader>
+              <CardTitle className="flex items-center gap-2 text-red-600">
+                <AlertTriangle className="h-5 w-5" />
+                Something went wrong
+              </CardTitle>
+              <CardDescription>
+                An unexpected error occurred. Please try again.
+              </CardDescription>
+            </CardHeader>
+            <CardContent className="space-y-4">
+              {process.env.NODE_ENV === 'development' && this.state.error && (
+                <div className="p-3 bg-red-50 dark:bg-red-900/20 rounded-lg">
+                  <p className="text-xs font-mono text-red-800 dark:text-red-200">
+                    {this.state.error.message}
+                  </p>
+                </div>
+              )}
+              <div className="flex gap-2">
+                <Button onClick={this.handleReset} variant="outline">
+                  Try Again
+                </Button>
+                <Button onClick={() => window.location.href = '/'}>
+                  Go Home
+                </Button>
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+      )
+    }
+
+    return this.props.children
+  }
+}
+```
+
+### 4. Usage Examples
+
+Using the error handler in components:
+
+```typescript
+// In your components
+import { ErrorHandler } from '@/lib/error-handler'
+
+// Example usage
+try {
+  const result = await sdk.auth.signInWithPassword(credentials)
+  // Success handling
+} catch (error) {
+  ErrorHandler.handle(error, {
+    operation: 'signInWithPassword',
+    details: { email: credentials.email }
+  })
+}
+
+// Using enhanced token manager
+import { TokenManagerEnhanced } from '@/lib/token-manager-enhanced'
+
+// Start auto-refresh when user logs in
+TokenManagerEnhanced.startAutoRefresh()
+
+// Stop when user logs out
+TokenManagerEnhanced.stopAutoRefresh()
+```
+
+## Validation Checklist
+
+✅ **Error Handling**:
+- SweetPotatoAPIError imported and used
+- Specific error codes handled
+- User-friendly messages shown
+- Toast notifications for all errors
+
+✅ **Token Management**:
+- TokenManager.isTokenExpired used
+- Auto-refresh implemented
+- Refresh failures handled
+- Cleanup on logout
+
+✅ **Error Boundary**:
+- Error boundary wraps app
+- Fallback UI provided
+- Development errors shown
+- Reset functionality works
+
+## Common Mistakes to Avoid
+
+❌ **Generic error messages**:
+```typescript
+// WRONG - Not helpful
+catch (error) {
+  toast.error('Error occurred')
+}
+```
+
+❌ **Not checking token expiry**:
+```typescript
+// WRONG - Token might be expired
+const token = TokenManager.getAccessToken()
+// Use without checking expiry
+```
+
+❌ **Missing error boundaries**:
+```typescript
+// WRONG - No error boundary
+<App />  // Uncaught errors crash app
+```
+
+## Next Step
+
+When ALL todos are ✅ complete:
+
+```javascript
+mcp__product-manager__get_agent_instructions({
+  category: "spaps-integration",
+  project: "spaps-demo",
+  step: 11
+})
+```
+
+## Summary
+
+Comprehensive error handling provides:
+- **Better UX** - Clear, actionable error messages
+- **Resilience** - App doesn't crash on errors
+- **Security** - Tokens managed properly
+- **Debugging** - Detailed error tracking