spaps-mcp 0.1.0

package/dist/wizard/step-06-magic-link.md

@@ -0,0 +1,560 @@
+# SPAPS Integration Step 6/12: Magic Link Authentication
+
+## Prerequisites Check
+
+Before starting, confirm you have completed:
+- ✅ Step 1-5: Full setup with email and wallet authentication
+- ✅ TokenManager working properly
+- ✅ Error handling implemented
+
+## Required TodoWrite List
+
+Create a TodoWrite with EXACTLY these items:
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Add magic link tab to auth component", status: "pending", activeForm: "Adding magic link tab" },
+    { content: "Create magic link request form", status: "pending", activeForm: "Creating magic link form" },
+    { content: "Implement requestMagicLink method", status: "pending", activeForm: "Implementing requestMagicLink" },
+    { content: "Add redirect_url parameter", status: "pending", activeForm: "Adding redirect URL" },
+    { content: "Handle success/error states", status: "pending", activeForm: "Handling response states" },
+    { content: "Create callback page for magic link", status: "pending", activeForm: "Creating callback page" },
+    { content: "Show user feedback with toast", status: "pending", activeForm: "Adding user feedback" },
+    { content: "Request step 7 of SPAPS integration wizard", status: "pending", activeForm: "Requesting next step" }
+  ]
+})
+```
+
+## Magic Link Implementation
+
+### Critical Parameter: redirect_url
+
+⚠️ **IMPORTANT**: The `requestMagicLink` method requires BOTH `email` and `redirect_url` parameters:
+
+```typescript
+// ✅ CORRECT - Both parameters required
+await sdk.auth.requestMagicLink({
+  email: 'user@example.com',
+  redirect_url: 'http://localhost:3000/auth/callback'  // REQUIRED!
+})
+
+// ❌ WRONG - Missing redirect_url will cause errors
+await sdk.auth.requestMagicLink({
+  email: 'user@example.com'  // Missing redirect_url!
+})
+
+// ❌ WRONG - Wrong parameter name
+await sdk.auth.requestMagicLink({
+  email: 'user@example.com',
+  redirectUrl: 'http://localhost:3000/auth/callback'  // Wrong! Use redirect_url
+})
+```
+
+**What redirect_url does:**
+- Where the user goes after clicking the magic link
+- Must be a complete URL (including protocol)
+- Usually your app's callback page
+- Example: `http://localhost:3000/auth/callback`
+
+### 1. Magic Link Request Form
+
+Add to your existing auth component or create new:
+
+```typescript
+// components/auth/magic-link-form.tsx
+'use client'
+
+import { useState } from 'react'
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
+import { toast } from "sonner"
+import { sdk } from '@/lib/spaps'
+import { SweetPotatoAPIError } from 'spaps-sdk'
+import { Mail, Loader2 } from 'lucide-react'
+
+export function MagicLinkForm() {
+  const [email, setEmail] = useState('')
+  const [isLoading, setIsLoading] = useState(false)
+  const [isSent, setIsSent] = useState(false)
+
+  const handleMagicLink = async (e: React.FormEvent) => {
+    e.preventDefault()
+    
+    if (!email) {
+      toast.error('Please enter your email address')
+      return
+    }
+
+    setIsLoading(true)
+    setIsSent(false)
+
+    try {
+      // ✅ CORRECT: Use requestMagicLink with proper parameters
+      // The redirect_url MUST be a complete URL where users go after clicking the link
+      await sdk.auth.requestMagicLink({
+        email: email.trim(),
+        redirect_url: `${window.location.origin}/auth/callback`  // Complete URL required
+      })
+      
+      setIsSent(true)
+      toast.success('Magic link sent! Check your email.')
+      
+      // Optional: Clear form after success
+      setTimeout(() => {
+        setEmail('')
+        setIsSent(false)
+      }, 30000) // Reset after 30 seconds
+      
+    } catch (error) {
+      if (error instanceof SweetPotatoAPIError) {
+        switch (error.code) {
+          case 'INVALID_EMAIL':
+            toast.error('Please enter a valid email address')
+            break
+          case 'USER_NOT_FOUND':
+            toast.error('No account found with this email')
+            break
+          case 'RATE_LIMITED':
+            toast.error('Too many requests. Please wait before trying again.')
+            break
+          case 'EMAIL_PROVIDER_ERROR':
+            toast.error('Failed to send email. Please try again.')
+            break
+          default:
+            toast.error(error.message || 'Failed to send magic link')
+        }
+      } else {
+        toast.error('An unexpected error occurred')
+      }
+      console.error('Magic link error:', error)
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const handleResend = () => {
+    setIsSent(false)
+    handleMagicLink(new Event('submit') as any)
+  }
+
+  return (
+    <Card className="w-[400px]">
+      <CardHeader>
+        <CardTitle>Magic Link Sign In</CardTitle>
+        <CardDescription>
+          We'll email you a secure link to sign in instantly
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <form onSubmit={handleMagicLink} className="space-y-4">
+          {!isSent ? (
+            <>
+              <div className="space-y-2">
+                <Label htmlFor="magic-email">Email Address</Label>
+                <Input
+                  id="magic-email"
+                  type="email"
+                  value={email}
+                  onChange={(e) => setEmail(e.target.value)}
+                  placeholder="your@email.com"
+                  required
+                  disabled={isLoading}
+                />
+              </div>
+              
+              <Button 
+                type="submit" 
+                className="w-full" 
+                disabled={isLoading}
+              >
+                {isLoading ? (
+                  <>
+                    <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+                    Sending...
+                  </>
+                ) : (
+                  <>
+                    <Mail className="mr-2 h-4 w-4" />
+                    Send Magic Link
+                  </>
+                )}
+              </Button>
+            </>
+          ) : (
+            <div className="space-y-4">
+              <div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
+                <p className="text-sm text-green-800 dark:text-green-200">
+                  ✅ Magic link sent to <strong>{email}</strong>
+                </p>
+                <p className="text-xs text-green-600 dark:text-green-400 mt-2">
+                  Check your email and click the link to sign in.
+                </p>
+              </div>
+              
+              <Button 
+                variant="outline" 
+                className="w-full"
+                onClick={handleResend}
+              >
+                Resend Magic Link
+              </Button>
+            </div>
+          )}
+          
+          <p className="text-xs text-muted-foreground text-center">
+            {isSent 
+              ? "Didn't receive it? Check your spam folder or resend."
+              : "No password needed. Just click the link in your email."}
+          </p>
+        </form>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+### 2. Magic Link Callback Page
+
+Create a page to handle the magic link callback:
+
+```typescript
+// app/auth/callback/page.tsx
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useRouter, useSearchParams } from 'next/navigation'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
+import { toast } from "sonner"
+import { sdk, TokenManager } from '@/lib/spaps'
+import { Loader2 } from 'lucide-react'
+
+export default function MagicLinkCallback() {
+  const router = useRouter()
+  const searchParams = useSearchParams()
+  const [status, setStatus] = useState<'verifying' | 'success' | 'error'>('verifying')
+  const [error, setError] = useState<string>('')
+
+  useEffect(() => {
+    const verifyMagicLink = async () => {
+      const token = searchParams.get('token')
+      const email = searchParams.get('email')
+      
+      if (!token) {
+        setStatus('error')
+        setError('Invalid magic link. Token missing.')
+        return
+      }
+
+      try {
+        // Verify the magic link token
+        const authResponse = await sdk.auth.verifyMagicLink({
+          token,
+          email: email || undefined
+        })
+        
+        // Store tokens
+        TokenManager.storeTokens(authResponse)
+        
+        // Setup auto-refresh
+        TokenManager.autoRefreshToken(sdk)
+        
+        setStatus('success')
+        toast.success('Successfully signed in!')
+        
+        // Redirect after short delay
+        setTimeout(() => {
+          router.push('/dashboard') // Or wherever you want
+        }, 2000)
+        
+      } catch (error: any) {
+        setStatus('error')
+        setError(error.message || 'Failed to verify magic link')
+        toast.error('Magic link verification failed')
+        console.error('Magic link verification error:', error)
+      }
+    }
+
+    verifyMagicLink()
+  }, [searchParams, router])
+
+  return (
+    <div className="min-h-screen flex items-center justify-center p-4">
+      <Card className="w-[400px]">
+        <CardHeader>
+          <CardTitle>
+            {status === 'verifying' && 'Verifying Magic Link...'}
+            {status === 'success' && 'Success!'}
+            {status === 'error' && 'Verification Failed'}
+          </CardTitle>
+          <CardDescription>
+            {status === 'verifying' && 'Please wait while we sign you in'}
+            {status === 'success' && 'You have been successfully authenticated'}
+            {status === 'error' && 'There was a problem with your magic link'}
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          {status === 'verifying' && (
+            <div className="flex justify-center py-8">
+              <Loader2 className="h-8 w-8 animate-spin text-primary" />
+            </div>
+          )}
+          
+          {status === 'success' && (
+            <div className="text-center py-8">
+              <div className="text-green-600 text-5xl mb-4">✓</div>
+              <p className="text-sm text-muted-foreground">
+                Redirecting to your dashboard...
+              </p>
+            </div>
+          )}
+          
+          {status === 'error' && (
+            <div className="space-y-4">
+              <div className="text-center py-4">
+                <div className="text-red-600 text-5xl mb-4">✗</div>
+                <p className="text-sm text-red-600">
+                  {error}
+                </p>
+              </div>
+              <div className="space-y-2">
+                <Button 
+                  variant="outline" 
+                  className="w-full"
+                  onClick={() => router.push('/auth')}
+                >
+                  Back to Sign In
+                </Button>
+                <Button 
+                  className="w-full"
+                  onClick={() => router.push('/auth?tab=magic')}
+                >
+                  Request New Magic Link
+                </Button>
+              </div>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  )
+}
+```
+
+### 3. Integration with Tabs
+
+Add magic link to your main auth component:
+
+```typescript
+// components/auth/auth-tabs.tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
+import { EmailAuthForm } from './email-auth-form'
+import { WalletAuthForm } from './wallet-auth-form'
+import { MagicLinkForm } from './magic-link-form'
+
+export function AuthTabs() {
+  return (
+    <Tabs defaultValue="email" className="w-[400px]">
+      <TabsList className="grid w-full grid-cols-3">
+        <TabsTrigger value="email">Email</TabsTrigger>
+        <TabsTrigger value="wallet">Wallet</TabsTrigger>
+        <TabsTrigger value="magic">Magic Link</TabsTrigger>
+      </TabsList>
+      
+      <TabsContent value="email">
+        <EmailAuthForm />
+      </TabsContent>
+      
+      <TabsContent value="wallet">
+        <WalletAuthForm />
+      </TabsContent>
+      
+      <TabsContent value="magic">
+        <MagicLinkForm />
+      </TabsContent>
+    </Tabs>
+  )
+}
+```
+
+## Method Signatures
+
+```typescript
+// Request magic link
+sdk.auth.requestMagicLink({
+  email: string,
+  redirect_url?: string  // Where to redirect after verification
+}): Promise<void>
+
+// Verify magic link (on callback page)
+sdk.auth.verifyMagicLink({
+  token: string,
+  email?: string  // Optional, for extra validation
+}): Promise<AuthResponse>
+```
+
+## Complete Working Example
+
+Here's the complete flow with all required pieces:
+
+### Step 1: Request Magic Link
+```typescript
+// In your component
+const handleMagicLink = async () => {
+  try {
+    // ✅ CORRECT: Both email and redirect_url required
+    await sdk.auth.requestMagicLink({
+      email: 'test@example.com',
+      redirect_url: 'http://localhost:3000/auth/callback'  // MUST be complete URL
+    })
+    
+    console.log('Magic link sent successfully!')
+    // Show success UI to user
+    
+  } catch (error) {
+    console.error('Failed to send magic link:', error)
+  }
+}
+```
+
+### Step 2: User Clicks Link in Email
+The magic link will look like:
+```
+http://localhost:3000/auth/callback?token=abc123&email=test@example.com
+```
+
+### Step 3: Callback Page Handles Verification
+```typescript
+// app/auth/callback/page.tsx
+const token = searchParams.get('token')
+const email = searchParams.get('email')
+
+// ✅ CORRECT: Verify the magic link
+const authResponse = await sdk.auth.verifyMagicLink({
+  token: token!,
+  email: email || undefined  // Optional but recommended
+})
+
+// Store tokens and redirect
+TokenManager.storeTokens(authResponse)
+router.push('/dashboard')
+```
+
+### Step 4: URLs Must Match
+⚠️ **CRITICAL**: The redirect_url in your request MUST match your callback page route:
+
+```typescript
+// If your callback page is at app/auth/callback/page.tsx
+// Then redirect_url MUST be:
+redirect_url: `${window.location.origin}/auth/callback`
+
+// NOT these:
+redirect_url: '/auth/callback'                    // Missing protocol/domain
+redirect_url: 'http://localhost:3000/callback'   // Wrong path
+redirect_url: `${window.location.origin}/login`  // Wrong path
+```
+
+## Validation Checklist
+
+✅ **Implementation**:
+- `requestMagicLink` method called correctly
+- `redirect_url` parameter included
+- Success state shows confirmation
+- Callback page handles verification
+
+✅ **User Experience**:
+- Clear success message after sending
+- Loading states during request
+- Resend option available
+- Helpful error messages
+
+✅ **Error Handling**:
+- Invalid email format
+- User not found
+- Rate limiting
+- Email provider errors
+
+✅ **Testing**:
+- Can request magic link
+- Email shows as sent
+- Callback page loads
+- Tokens stored after verification
+
+## Common Mistakes to Avoid
+
+❌ **Forgetting redirect URL**:
+```typescript
+// WRONG - Missing redirect_url
+await sdk.auth.requestMagicLink({ email })
+```
+
+❌ **Not handling sent state**:
+```typescript
+// WRONG - No feedback that email was sent
+await sdk.auth.requestMagicLink(...)
+// User doesn't know if it worked
+```
+
+❌ **Missing callback page**:
+```typescript
+// WRONG - Redirect URL points to non-existent page
+redirect_url: '/auth/callback'  // But page doesn't exist!
+```
+
+## Testing Magic Links
+
+### Local Development
+
+In local mode, SPAPS will:
+1. Log the magic link to console (no real email sent)
+2. You can copy the link from terminal
+3. Open in browser to test callback
+
+### Test Flow
+
+1. Enter email: `test@example.com`
+2. Click "Send Magic Link"
+3. Check terminal for link (local mode)
+4. Open link in browser
+5. Should authenticate and redirect
+
+### Email Templates
+
+SPAPS uses default email templates. In production, you can customize:
+- Subject line
+- Email body
+- Branding
+- Link expiration time
+
+## Security Considerations
+
+⚠️ **Important Security Notes**:
+- Magic links expire after 15 minutes
+- Single use only (can't reuse link)
+- Rate limited to prevent abuse
+- Verify token server-side
+- Use HTTPS in production
+
+## Next Step
+
+When ALL todos are ✅ complete and magic links work:
+
+```javascript
+mcp__product-manager__get_agent_instructions({
+  category: "spaps-integration",
+  project: "spaps-demo",
+  step: 7
+})
+```
+
+## Summary
+
+Magic link authentication provides:
+- **Passwordless login** - No passwords to remember
+- **Better security** - No password to steal
+- **Simple UX** - Just click the email link
+- **Mobile friendly** - Works great on phones
+
+Remember to test the full flow from request to callback!