spaps-mcp 0.1.0

package/dist/wizard/step-12-testing.md

@@ -0,0 +1,588 @@
+# SPAPS Integration Step 12/12: Testing & Documentation
+
+## Prerequisites Check
+
+Before starting, confirm you have completed:
+- ✅ Step 1-11: Complete implementation with UI polish
+- ✅ All authentication methods working
+- ✅ Payments and admin features functional
+- ✅ Error handling and theming complete
+
+## Required TodoWrite List
+
+Create a TodoWrite with EXACTLY these items:
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Test email login with test@example.com / Test123!", status: "pending", activeForm: "Testing email authentication" },
+    { content: "Test wallet with 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8", status: "pending", activeForm: "Testing wallet authentication" },
+    { content: "Test Stripe with card 4242 4242 4242 4242", status: "pending", activeForm: "Testing Stripe payments" },
+    { content: "Test whitelist with vip@example.com", status: "pending", activeForm: "Testing whitelist check" },
+    { content: "Verify token auto-refresh is working", status: "pending", activeForm: "Verifying token refresh" },
+    { content: "Create comprehensive README.md", status: "pending", activeForm: "Creating README documentation" },
+    { content: "Run npm run dev and verify everything works", status: "pending", activeForm: "Running final verification" },
+    { content: "Mark SPAPS integration complete! 🎉", status: "pending", activeForm: "Completing integration" }
+  ]
+})
+```
+
+## Comprehensive Testing Guide
+
+### 1. Test Authentication Methods
+
+#### Email/Password Test
+```typescript
+// Test credentials
+const testUser = {
+  email: 'test@example.com',
+  password: 'Test123!'
+}
+
+// Expected behavior:
+// 1. Login succeeds
+// 2. Tokens stored in localStorage
+// 3. User redirected to dashboard
+// 4. Auto-refresh works
+```
+
+#### Wallet Authentication Test
+```typescript
+// Test wallet
+const testWallet = '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8'
+
+// Expected behavior:
+// 1. MetaMask prompts for signature
+// 2. Authentication succeeds
+// 3. Tokens stored
+// 4. Wallet address displayed
+```
+
+#### Magic Link Test
+```typescript
+// Test flow:
+// 1. Request magic link for test@example.com
+// 2. Check console/terminal for link (local mode)
+// 3. Open link in browser
+// 4. Should authenticate and redirect
+```
+
+### 2. Test Payment Integration
+
+#### Stripe Checkout Test
+```javascript
+// Test card numbers:
+const testCards = {
+  success: '4242 4242 4242 4242',
+  declined: '4000 0000 0000 0002',
+  requires3DS: '4000 0025 0000 3155'
+}
+
+// Test data:
+// - Any future expiry date
+// - Any 3-digit CVC
+// - Any ZIP code
+```
+
+#### Customer Portal Test
+```javascript
+// Expected behavior:
+// 1. Click "Open Customer Portal"
+// 2. Redirects to Stripe portal
+// 3. Can manage subscriptions
+// 4. Returns to app after
+```
+
+### 3. Test Admin Features
+
+#### Whitelist Test
+```javascript
+// Test emails:
+const whitelistTest = {
+  vip: 'vip@example.com',      // Should be whitelisted
+  regular: 'user@example.com'  // Should NOT be whitelisted
+}
+
+// Admin credentials:
+const admin = {
+  email: 'admin@example.com',
+  password: 'Admin123!'
+}
+```
+
+#### Product Sync Test
+```javascript
+// Expected behavior:
+// 1. Login as admin
+// 2. Navigate to admin panel
+// 3. Click "Sync Products"
+// 4. Products sync from Stripe
+// 5. Success message shown
+```
+
+### 4. Test Error Scenarios
+
+```typescript
+// components/test/error-tests.tsx
+'use client'
+
+import { Button } from "@/components/ui/button"
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
+import { sdk } from '@/lib/spaps'
+import { ErrorHandler } from '@/lib/error-handler'
+
+export function ErrorTests() {
+  const testScenarios = [
+    {
+      name: 'Invalid Credentials',
+      test: async () => {
+        try {
+          await sdk.auth.signInWithPassword({
+            email: 'test@example.com',
+            password: 'WrongPassword'
+          })
+        } catch (error) {
+          ErrorHandler.handle(error, { operation: 'testInvalidCredentials' })
+        }
+      }
+    },
+    {
+      name: 'Rate Limiting',
+      test: async () => {
+        // Make 10 rapid requests
+        for (let i = 0; i < 10; i++) {
+          try {
+            await sdk.auth.signInWithPassword({
+              email: `test${i}@example.com`,
+              password: 'Test123!'
+            })
+          } catch (error) {
+            ErrorHandler.handle(error, { operation: 'testRateLimiting' })
+          }
+        }
+      }
+    },
+    {
+      name: 'Network Error',
+      test: async () => {
+        // Temporarily break the API URL
+        const originalUrl = process.env.NEXT_PUBLIC_SPAPS_API_URL
+        process.env.NEXT_PUBLIC_SPAPS_API_URL = 'http://localhost:9999'
+        
+        try {
+          await sdk.auth.signInWithPassword({
+            email: 'test@example.com',
+            password: 'Test123!'
+          })
+        } catch (error) {
+          ErrorHandler.handle(error, { operation: 'testNetworkError' })
+        } finally {
+          process.env.NEXT_PUBLIC_SPAPS_API_URL = originalUrl
+        }
+      }
+    }
+  ]
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Error Handling Tests</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-2">
+        {testScenarios.map((scenario) => (
+          <Button
+            key={scenario.name}
+            variant="outline"
+            onClick={scenario.test}
+            className="w-full justify-start"
+          >
+            Test: {scenario.name}
+          </Button>
+        ))}
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+### 5. Create Test Checklist Component
+
+```typescript
+// components/test/test-checklist.tsx
+'use client'
+
+import { useState } from 'react'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
+import { Checkbox } from "@/components/ui/checkbox"
+import { Badge } from "@/components/ui/badge"
+import { Progress } from "@/components/ui/progress"
+
+const testItems = [
+  { id: 'email-auth', label: 'Email authentication works', category: 'auth' },
+  { id: 'wallet-auth', label: 'Wallet authentication works', category: 'auth' },
+  { id: 'magic-link', label: 'Magic link works', category: 'auth' },
+  { id: 'token-storage', label: 'Tokens stored in localStorage', category: 'auth' },
+  { id: 'auto-refresh', label: 'Token auto-refresh works', category: 'auth' },
+  { id: 'stripe-checkout', label: 'Stripe checkout works', category: 'payments' },
+  { id: 'customer-portal', label: 'Customer portal accessible', category: 'payments' },
+  { id: 'product-list', label: 'Products load from Stripe', category: 'payments' },
+  { id: 'whitelist-check', label: 'Whitelist check works', category: 'admin' },
+  { id: 'admin-auth', label: 'Admin authentication works', category: 'admin' },
+  { id: 'product-sync', label: 'Product sync works', category: 'admin' },
+  { id: 'error-handling', label: 'Errors show proper messages', category: 'errors' },
+  { id: 'dark-mode', label: 'Dark mode toggle works', category: 'ui' },
+  { id: 'responsive', label: 'Responsive on mobile', category: 'ui' },
+  { id: 'loading-states', label: 'Loading states display', category: 'ui' }
+]
+
+export function TestChecklist() {
+  const [checked, setChecked] = useState<string[]>([])
+  
+  const progress = (checked.length / testItems.length) * 100
+  
+  const handleCheck = (itemId: string) => {
+    setChecked(prev => 
+      prev.includes(itemId) 
+        ? prev.filter(id => id !== itemId)
+        : [...prev, itemId]
+    )
+  }
+
+  const categories = [...new Set(testItems.map(item => item.category))]
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Integration Test Checklist</CardTitle>
+        <CardDescription>
+          Verify all features are working correctly
+        </CardDescription>
+        <Progress value={progress} className="mt-2" />
+        <p className="text-sm text-muted-foreground">
+          {checked.length} of {testItems.length} tests passed
+        </p>
+      </CardHeader>
+      <CardContent>
+        {categories.map(category => (
+          <div key={category} className="mb-6">
+            <h3 className="font-semibold mb-3 capitalize">
+              {category}
+              <Badge variant="outline" className="ml-2">
+                {checked.filter(id => 
+                  testItems.find(item => item.id === id)?.category === category
+                ).length}/{testItems.filter(item => item.category === category).length}
+              </Badge>
+            </h3>
+            <div className="space-y-2">
+              {testItems
+                .filter(item => item.category === category)
+                .map(item => (
+                  <div key={item.id} className="flex items-center space-x-2">
+                    <Checkbox
+                      id={item.id}
+                      checked={checked.includes(item.id)}
+                      onCheckedChange={() => handleCheck(item.id)}
+                    />
+                    <label
+                      htmlFor={item.id}
+                      className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
+                    >
+                      {item.label}
+                    </label>
+                  </div>
+                ))}
+            </div>
+          </div>
+        ))}
+        
+        {progress === 100 && (
+          <div className="mt-6 p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
+            <p className="text-green-800 dark:text-green-200 font-semibold">
+              🎉 All tests passed! Your SPAPS integration is complete!
+            </p>
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+### 6. Create README.md
+
+```markdown
+# SPAPS Demo - Next.js Integration
+
+A complete implementation of Sweet Potato Authentication & Payment Service (SPAPS) with Next.js 15, TypeScript, and shadcn/ui.
+
+## Features
+
+✅ **Multi-Method Authentication**
+- Email/Password login
+- Ethereum wallet authentication
+- Magic link (passwordless)
+- Token auto-refresh
+
+✅ **Stripe Payment Integration**
+- One-time payments
+- Subscriptions
+- Customer portal
+- Product synchronization
+
+✅ **Admin Features**
+- Whitelist management
+- User administration
+- Product sync from Stripe
+- System statistics
+
+✅ **Modern UI/UX**
+- Dark mode support
+- Responsive design
+- Loading states
+- Error handling with toasts
+
+## Tech Stack
+
+- **Framework**: Next.js 15 with App Router
+- **Language**: TypeScript
+- **UI**: shadcn/ui components
+- **Styling**: Tailwind CSS
+- **Authentication**: SPAPS SDK
+- **Payments**: Stripe (via SPAPS)
+- **State**: React hooks
+- **Themes**: next-themes
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- npm or yarn
+- SPAPS CLI (`npm install -D spaps`)
+
+### Installation
+
+1. Clone the repository:
+\`\`\`bash
+git clone <repo-url>
+cd spaps-demo
+\`\`\`
+
+2. Install dependencies:
+\`\`\`bash
+npm install
+\`\`\`
+
+3. Copy environment variables:
+\`\`\`bash
+cp .env.local.example .env.local
+\`\`\`
+
+4. Update `.env.local` with your credentials:
+\`\`\`env
+NEXT_PUBLIC_SPAPS_API_URL=http://localhost:3301
+SPAPS_API_KEY=test_key_local_dev_only
+NEXT_PUBLIC_ADMIN_EMAIL=admin@example.com
+NEXT_PUBLIC_ADMIN_PASSWORD=Admin123!
+\`\`\`
+
+### Running the Application
+
+Start both SPAPS local server and Next.js:
+
+\`\`\`bash
+npm run dev
+\`\`\`
+
+This runs:
+- SPAPS on http://localhost:3301
+- Next.js on http://localhost:3000
+
+## Testing
+
+### Test Credentials
+
+**User Account:**
+- Email: test@example.com
+- Password: Test123!
+
+**Admin Account:**
+- Email: admin@example.com
+- Password: Admin123!
+
+**Test Wallet:**
+- Address: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8
+
+**Test Card (Stripe):**
+- Number: 4242 4242 4242 4242
+- Expiry: Any future date
+- CVC: Any 3 digits
+
+### Running Tests
+
+1. **Authentication**: Test all login methods
+2. **Payments**: Create test payment with Stripe
+3. **Whitelist**: Check vip@example.com
+4. **Admin**: Login as admin and sync products
+5. **Errors**: Try wrong password to see error handling
+
+## Project Structure
+
+\`\`\`
+spaps-demo/
+├── app/                    # Next.js app router pages
+│   ├── api/               # API routes
+│   ├── auth/              # Authentication pages
+│   ├── dashboard/         # Dashboard
+│   └── layout.tsx         # Root layout with providers
+├── components/            # React components
+│   ├── auth/             # Auth forms
+│   ├── payments/         # Payment components
+│   ├── admin/            # Admin panel
+│   └── ui/               # shadcn/ui components
+├── lib/                   # Utilities
+│   ├── spaps.ts          # SPAPS SDK initialization
+│   ├── admin-service.ts  # Admin API service
+│   └── error-handler.ts  # Error handling
+└── public/               # Static assets
+\`\`\`
+
+## API Integration
+
+The app integrates with SPAPS API on port 3301:
+
+- **Authentication**: /api/auth/*
+- **Payments**: /api/stripe/*
+- **Admin**: /api/v1/admin/*
+- **Whitelist**: Direct API calls with JWT
+
+## Deployment
+
+### Environment Variables
+
+Set these in your deployment platform:
+
+- `NEXT_PUBLIC_SPAPS_API_URL` - SPAPS API endpoint
+- `SPAPS_API_KEY` - Your API key
+- `NEXT_PUBLIC_ADMIN_EMAIL` - Admin email
+- `NEXT_PUBLIC_ADMIN_PASSWORD` - Admin password
+
+### Build
+
+\`\`\`bash
+npm run build
+npm start
+\`\`\`
+
+## Common Issues
+
+### Port 3301 Already in Use
+\`\`\`bash
+lsof -i :3301
+kill -9 <PID>
+\`\`\`
+
+### SPAPS Not Starting
+Check package.json dev script includes:
+\`\`\`json
+"dev": "concurrently \"npx spaps local\" \"next dev\""
+\`\`\`
+
+### Wallet Not Connecting
+- Ensure MetaMask is installed
+- Switch to Ethereum Mainnet
+- Check console for errors
+
+## License
+
+MIT
+
+## Support
+
+For issues or questions:
+- GitHub Issues: [repo-url]/issues
+- Documentation: https://docs.sweetpotato.dev
+```
+
+## Final Verification Checklist
+
+Run through this final checklist:
+
+```bash
+# 1. Start the application
+npm run dev
+
+# 2. Check SPAPS is running
+curl http://localhost:3301/health
+
+# 3. Check Next.js is running
+curl http://localhost:3000
+
+# 4. Run through all test scenarios
+# - Login with email
+# - Connect wallet
+# - Make test payment
+# - Check whitelist
+# - Access admin panel
+
+# 5. Verify no console errors
+# Check browser DevTools console
+
+# 6. Test responsive design
+# Open DevTools and test mobile view
+
+# 7. Test dark mode
+# Toggle theme and check all pages
+```
+
+## Success Criteria
+
+Your integration is complete when:
+
+✅ All authentication methods work
+✅ Payments process successfully
+✅ Whitelist checks function
+✅ Admin panel accessible
+✅ Tokens auto-refresh
+✅ Errors handled gracefully
+✅ UI is responsive
+✅ Dark mode works
+✅ README is comprehensive
+✅ No console errors
+
+## Congratulations! 🎉
+
+You've successfully integrated SPAPS with:
+- **12 completed steps**
+- **Full authentication system**
+- **Stripe payment processing**
+- **Admin capabilities**
+- **Beautiful UI with shadcn/ui**
+- **Comprehensive error handling**
+- **Complete documentation**
+
+## Integration Complete!
+
+Your SPAPS integration is now:
+- ✅ **Fully functional**
+- ✅ **Production ready**
+- ✅ **Well documented**
+- ✅ **Properly tested**
+
+## Summary
+
+This wizard has guided you through:
+1. ✅ Project setup with correct dependencies
+2. ✅ Environment configuration with port 3301
+3. ✅ SDK initialization with proper exports
+4. ✅ Email/password authentication
+5. ✅ Wallet authentication with correct method
+6. ✅ Magic link implementation
+7. ✅ Stripe payment integration
+8. ✅ Whitelist operations
+9. ✅ Admin panel implementation
+10. ✅ Error handling and token management
+11. ✅ UI polish with theming
+12. ✅ Testing and documentation
+
+**Great job completing the SPAPS Integration Wizard!** 🚀

package/dist/wizard/wizard.lock

@@ -0,0 +1,67 @@
+{
+  "version": 1,
+  "source": "agent-instructions/spaps-wizard-steps",
+  "hash_normalization": "sha256 over UTF-8 bytes with CRLF/CR normalized to LF",
+  "steps": [
+    {
+      "index": 1,
+      "path": "step-01-setup.md",
+      "sha256": "888010e84660a5128debb8cb7de996ec3e1c491da673970bf9a10771d63cb24a"
+    },
+    {
+      "index": 2,
+      "path": "step-02-environment.md",
+      "sha256": "2fd442f18f3190c3ca24ff92fd5f4ff987bdfd15e5e3906edbb2fe8bfef352cb"
+    },
+    {
+      "index": 3,
+      "path": "step-03-sdk-init.md",
+      "sha256": "6c9ca363bce832b202e9f6bd6ebf6911b41329421eabb6bef40434bb20e51d0d"
+    },
+    {
+      "index": 4,
+      "path": "step-04-email-auth.md",
+      "sha256": "b267ea839069913630207e71a4069a9981e2810b916c4d9b386df1b35d9a41a5"
+    },
+    {
+      "index": 5,
+      "path": "step-05-wallet-auth.md",
+      "sha256": "bb97f56f0cea87b2c1729d8005c2ee83a3b9dd0c166eab3ce1089aa71881f6cf"
+    },
+    {
+      "index": 6,
+      "path": "step-06-magic-link.md",
+      "sha256": "013204c2a9b49cf93c6398d63adabd807c3f1949b7e20126272feefbabf3e4b2"
+    },
+    {
+      "index": 7,
+      "path": "step-07-payments.md",
+      "sha256": "3e527fd805cf58c7c932a0ca286628a23c2aeaa51c4761f13069c1c7037afbf2"
+    },
+    {
+      "index": 8,
+      "path": "step-08-whitelist.md",
+      "sha256": "ad67b19b4b8d8ae99c877971923a10ed534343105c56c6d526a9b8dbc3f97d76"
+    },
+    {
+      "index": 9,
+      "path": "step-09-admin.md",
+      "sha256": "7cc16bd291a97daff7323dc581705b77903b8c62bbd224b90552a1f846eedc3a"
+    },
+    {
+      "index": 10,
+      "path": "step-10-errors.md",
+      "sha256": "dce6214466acb6c6f02b13ddb674bc532afd9f99b133dfbc3daff98139d9c9ec"
+    },
+    {
+      "index": 11,
+      "path": "step-11-ui-polish.md",
+      "sha256": "c8d07da3427fd5780769894ebd57eccad065e19211d64022dee07a541a87950d"
+    },
+    {
+      "index": 12,
+      "path": "step-12-testing.md",
+      "sha256": "9b756495cb2f416c9b01de24e30860596ca09b416379ecdc9182a80eb5d8f785"
+    }
+  ]
+}