spaps-mcp 0.1.0

package/dist/wizard/step-03-sdk-init.md

@@ -0,0 +1,351 @@
+# SPAPS Integration Step 3/12: SDK Initialization
+
+## Prerequisites Check
+
+Before starting, confirm you have completed:
+- ✅ Step 1: Dependencies installed including spaps-sdk
+- ✅ Step 2: Environment variables configured with port 3301
+- ✅ SPAPS running on localhost:3301
+
+## Required TodoWrite List
+
+Create a TodoWrite with EXACTLY these items:
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Create lib directory in project root", status: "pending", activeForm: "Creating lib directory" },
+    { content: "Create lib/spaps.ts file", status: "pending", activeForm: "Creating SDK initialization file" },
+    { content: "Import SweetPotatoSDK from 'spaps-sdk'", status: "pending", activeForm: "Importing SDK" },
+    { content: "Initialize SDK with localhost:3301", status: "pending", activeForm: "Initializing SDK with correct port" },
+    { content: "Export TokenManager and WalletUtils", status: "pending", activeForm: "Exporting utilities" },
+    { content: "Create type definitions if needed", status: "pending", activeForm: "Creating type definitions" },
+    { content: "Verify imports work correctly", status: "pending", activeForm: "Verifying SDK setup" },
+    { content: "Request step 4 of SPAPS integration wizard", status: "pending", activeForm: "Requesting next step" }
+  ]
+})
+```
+
+## SDK Initialization Guide
+
+### 1. Create Directory Structure
+
+```bash
+# From your project root
+mkdir -p lib
+touch lib/spaps.ts
+```
+
+### 2. Basic SDK Initialization
+
+⚠️ **CRITICAL PARAMETER NAME**: The constructor parameter is `apiUrl` (NOT `baseURL`)
+
+Create `lib/spaps.ts` with this EXACT content:
+
+```typescript
+// lib/spaps.ts
+import { SweetPotatoSDK, TokenManager, WalletUtils } from 'spaps-sdk';
+
+// Initialize the SDK with environment variables
+// ✅ CORRECT: Use 'apiUrl' as the parameter name
+const sdk = new SweetPotatoSDK({
+  apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL || 'http://localhost:3301',
+  apiKey: process.env.SPAPS_API_KEY || 'test_key_local_dev_only'
+});
+
+// Export everything needed
+export { sdk, TokenManager, WalletUtils };
+export default sdk;
+```
+
+### Common Parameter Naming Mistakes
+
+❌ **WRONG** - These parameter names DO NOT WORK:
+```typescript
+// WRONG - 'baseURL' doesn't exist
+const sdk = new SweetPotatoSDK({
+  baseURL: 'http://localhost:3301',  // NO!
+  apiKey: 'your_key'
+});
+
+// WRONG - 'url' doesn't exist  
+const sdk = new SweetPotatoSDK({
+  url: 'http://localhost:3301',      // NO!
+  apiKey: 'your_key'
+});
+
+// WRONG - 'endpoint' doesn't exist
+const sdk = new SweetPotatoSDK({
+  endpoint: 'http://localhost:3301', // NO!
+  apiKey: 'your_key'
+});
+```
+
+✅ **CORRECT** - Always use `apiUrl`:
+```typescript
+// CORRECT - This is the only parameter name that works
+const sdk = new SweetPotatoSDK({
+  apiUrl: 'http://localhost:3301',   // YES!
+  apiKey: 'your_key'
+});
+```
+
+### 3. Advanced Setup (Optional)
+
+For more control, you can create separate client and server instances:
+
+```typescript
+// lib/spaps.ts
+import { SweetPotatoSDK, TokenManager, WalletUtils, SweetPotatoAPIError } from 'spaps-sdk';
+import type { AuthResponse, User } from 'spaps-sdk';
+
+// Client-side SDK (for browser)
+const clientSDK = new SweetPotatoSDK({
+  apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL || 'http://localhost:3301',
+  apiKey: 'test_key_local_dev_only' // Public key for client
+});
+
+// Server-side SDK (for API routes/server actions)
+const serverSDK = new SweetPotatoSDK({
+  apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL || 'http://localhost:3301',
+  apiKey: process.env.SPAPS_API_KEY || 'test_key_local_dev_only'
+});
+
+// Determine which SDK to use based on environment
+const sdk = typeof window !== 'undefined' ? clientSDK : serverSDK;
+
+// Export everything applications need
+export { 
+  sdk,
+  clientSDK,
+  serverSDK,
+  TokenManager, 
+  WalletUtils,
+  SweetPotatoAPIError
+};
+
+// Export types
+export type { AuthResponse, User };
+
+// Default export
+export default sdk;
+```
+
+### 4. Type Definitions (if needed)
+
+If TypeScript can't find types, create:
+
+```typescript
+// types/spaps.d.ts
+declare module 'spaps-sdk' {
+  export class SweetPotatoSDK {
+    constructor(config: { apiUrl: string; apiKey: string });
+    auth: AuthService;
+    payments: PaymentsService;
+  }
+  
+  export class TokenManager {
+    static storeTokens(tokens: AuthResponse): void;
+    static getAccessToken(): string | null;
+    static getRefreshToken(): string | null;
+    static clearTokens(): void;
+    static isTokenExpired(token: string): boolean;
+    static autoRefreshToken(sdk: SweetPotatoSDK): Promise<boolean>;
+  }
+  
+  export class WalletUtils {
+    static detectChainType(address: string): string;
+    static validateAddress(address: string, chainType: string): boolean;
+  }
+  
+  export class SweetPotatoAPIError extends Error {
+    code?: string;
+    status?: number;
+  }
+  
+  // Add other types as needed
+}
+```
+
+### 5. Test Your Setup
+
+Create a test file to verify the SDK works:
+
+```typescript
+// app/api/test-sdk/route.ts
+import { NextResponse } from 'next/server';
+import { sdk } from '@/lib/spaps';
+
+export async function GET() {
+  try {
+    // Test that SDK is initialized
+    const sdkInfo = {
+      initialized: !!sdk,
+      hasAuth: !!sdk.auth,
+      hasPayments: !!sdk.payments,
+      apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL
+    };
+    
+    return NextResponse.json({ 
+      success: true, 
+      sdk: sdkInfo 
+    });
+  } catch (error: any) {
+    return NextResponse.json({ 
+      success: false, 
+      error: error.message 
+    });
+  }
+}
+```
+
+Test it:
+```bash
+curl http://localhost:3000/api/test-sdk
+```
+
+## Important SDK Details
+
+### Available SDK Methods
+
+The SDK provides these main services:
+
+```typescript
+sdk.auth       // Authentication methods
+sdk.payments   // Stripe payment methods
+```
+
+### What's NOT in the Main SDK
+
+Remember these are NOT in the main SDK:
+- ❌ `sdk.whitelist` - Use admin-utils or direct API
+- ❌ `sdk.admin` - Use direct API calls with JWT
+- ❌ `sdk.users` - User management via auth methods
+
+### Utility Classes Available
+
+These utilities are exported separately:
+- `TokenManager` - Token storage and management
+- `WalletUtils` - Wallet address utilities
+- `SweetPotatoAPIError` - Error handling class
+
+## Validation Checklist
+
+✅ **File Structure**:
+- `lib/spaps.ts` exists
+- Imports from 'spaps-sdk' (NOT @sweet-potato/sdk)
+- Exports sdk, TokenManager, WalletUtils
+
+✅ **SDK Configuration**:
+- Uses `http://localhost:3301` as API URL
+- Port is 3301 (NOT 3000, 3300, or 3456)
+- API key configured correctly
+
+✅ **Testing**:
+- Test endpoint returns success
+- SDK methods are accessible
+- No import errors in console
+
+## Common Mistakes to Avoid
+
+❌ **Wrong package name**:
+```typescript
+// WRONG
+import { SweetPotatoSDK } from 'spaps-sdk';
+import { SweetPotatoSDK } from 'sweetpotato-sdk';
+```
+
+❌ **Wrong port**:
+```typescript
+// WRONG
+apiUrl: 'http://localhost:3000'  // This is Next.js
+apiUrl: 'http://localhost:3301'  // Old port
+```
+
+❌ **Not exporting utilities**:
+```typescript
+// WRONG - Forgot to export utilities
+export { sdk };
+// Missing TokenManager and WalletUtils!
+```
+
+❌ **Hardcoding values**:
+```typescript
+// WRONG - Should use environment variables
+apiUrl: 'http://localhost:3301',  // Hardcoded
+apiKey: 'some-key'                // Hardcoded
+```
+
+## Using the SDK
+
+After initialization, you can use it like this:
+
+```typescript
+// In your components
+import { sdk, TokenManager } from '@/lib/spaps';
+
+// Email authentication
+const auth = await sdk.auth.signInWithPassword({
+  email: 'test@example.com',
+  password: 'Test123!'
+});
+TokenManager.storeTokens(auth);
+
+// Wallet authentication
+const walletAuth = await sdk.auth.authenticateWallet(
+  address,
+  signatureCallback,
+  'ethereum'
+);
+
+// Payments
+const products = await sdk.payments.listProducts();
+```
+
+## Troubleshooting
+
+### Module Not Found
+
+If you get "Cannot find module 'spaps-sdk'":
+```bash
+npm list spaps-sdk  # Check if installed
+npm install spaps-sdk  # Reinstall if needed
+```
+
+### Type Errors
+
+If TypeScript complains about types:
+1. Restart TypeScript server in VSCode
+2. Clear Next.js cache: `rm -rf .next`
+3. Check `tsconfig.json` includes your lib folder
+
+### Connection Errors
+
+If SDK can't connect to SPAPS:
+```bash
+# Check SPAPS is running
+curl http://localhost:3301/health
+
+# Check your dev script
+npm run dev  # Should start both SPAPS and Next.js
+```
+
+## Next Step
+
+When ALL todos are ✅ complete and SDK is initialized:
+
+```javascript
+mcp__product-manager__get_agent_instructions({
+  category: "spaps-integration",
+  project: "spaps-demo",
+  step: 4
+})
+```
+
+## Summary
+
+SDK initialization is the foundation for all SPAPS features:
+- **Correct package**: `spaps-sdk` (not @sweet-potato/sdk)
+- **Correct port**: 3301 (not 3000, 3300, or 3456)
+- **Export utilities**: TokenManager and WalletUtils
+- **Use environment variables**: Don't hardcode values

package/dist/wizard/step-04-email-auth.md

@@ -0,0 +1,311 @@
+# SPAPS Integration Step 4/12: Email/Password Authentication
+
+## Prerequisites Check
+
+Before starting, confirm you have completed:
+- ✅ Step 1: Project setup with spaps-sdk installed
+- ✅ Step 2: Environment configuration with port 3301
+- ✅ Step 3: SDK initialization in lib/spaps.ts
+
+## Required TodoWrite List
+
+Create a TodoWrite with EXACTLY these items:
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Create components/auth directory structure", status: "pending", activeForm: "Creating auth directory" },
+    { content: "Build email/password form with shadcn/ui components", status: "pending", activeForm: "Building authentication form" },
+    { content: "Implement signInWithPassword with OBJECT parameter", status: "pending", activeForm: "Implementing signInWithPassword" },
+    { content: "Add TokenManager.storeTokens for token storage", status: "pending", activeForm: "Adding token storage" },
+    { content: "Setup TokenManager.autoRefreshToken", status: "pending", activeForm: "Setting up auto-refresh" },
+    { content: "Implement SweetPotatoAPIError handling", status: "pending", activeForm: "Implementing error handling" },
+    { content: "Test with test@example.com / Test123!", status: "pending", activeForm: "Testing authentication" },
+    { content: "Request step 5 of SPAPS integration wizard", status: "pending", activeForm: "Requesting next step" }
+  ]
+})
+```
+
+## Implementation Guide
+
+### 1. Create Auth Component Structure
+```bash
+mkdir -p components/auth
+touch components/auth/email-auth-form.tsx
+```
+
+### 2. Import Requirements
+```typescript
+// ✅ CORRECT IMPORTS
+import { SweetPotatoSDK, TokenManager, SweetPotatoAPIError } from 'spaps-sdk';
+import { sdk } from '@/lib/spaps';
+
+// UI Components from shadcn/ui
+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"
+```
+
+### 3. Authentication Implementation
+
+⚠️ **CRITICAL - CORRECT METHOD SIGNATURE**:
+
+```typescript
+// ✅ CORRECT - Pass an OBJECT with email and password
+const authResponse = await sdk.auth.signInWithPassword({
+  email: 'test@example.com',
+  password: 'Test123!'
+});
+
+// ❌ WRONG - DO NOT pass as separate parameters
+const authResponse = await sdk.auth.signInWithPassword(email, password);
+```
+
+### 4. Token Management
+
+⚠️ **CRITICAL - CORRECT TOKEN STORAGE**:
+
+```typescript
+// ✅ CORRECT - Pass the auth response object
+TokenManager.storeTokens(authResponse);
+
+// Then setup auto-refresh
+TokenManager.autoRefreshToken(sdk);
+
+// ❌ WRONG - DO NOT pass tokens separately
+TokenManager.storeTokens(authResponse.access_token, authResponse.refresh_token);
+```
+
+### 5. Error Handling
+
+Implement specific error handling:
+
+```typescript
+try {
+  const auth = await sdk.auth.signInWithPassword({
+    email: email.trim(),
+    password: password
+  });
+  
+  TokenManager.storeTokens(auth);
+  TokenManager.autoRefreshToken(sdk);
+  
+  toast.success('Successfully authenticated!');
+  
+} catch (error) {
+  if (error instanceof SweetPotatoAPIError) {
+    switch (error.code) {
+      case 'INVALID_CREDENTIALS':
+        toast.error('Invalid email or password');
+        break;
+      case 'RATE_LIMITED':
+        toast.error('Too many attempts. Please wait before trying again.');
+        break;
+      case 'USER_NOT_FOUND':
+        toast.error('No account found with this email');
+        break;
+      default:
+        toast.error(error.message || 'Authentication failed');
+    }
+  } else {
+    toast.error('An unexpected error occurred');
+  }
+}
+```
+
+### 6. Complete Component Example
+
+```typescript
+'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, TokenManager } from 'spaps-sdk'
+
+export function EmailAuthForm() {
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setIsLoading(true)
+    
+    try {
+      // ✅ CORRECT: Pass object with email and password
+      const authResponse = await sdk.auth.signInWithPassword({
+        email: email.trim(),
+        password: password
+      });
+      
+      // ✅ CORRECT: Store tokens and setup auto-refresh
+      TokenManager.storeTokens(authResponse);
+      TokenManager.autoRefreshToken(sdk);
+      
+      toast.success('Successfully authenticated!');
+      // Handle success (e.g., redirect, update UI)
+      
+    } catch (error) {
+      if (error instanceof SweetPotatoAPIError) {
+        // Specific error handling
+        switch (error.code) {
+          case 'INVALID_CREDENTIALS':
+            toast.error('Invalid email or password');
+            break;
+          case 'RATE_LIMITED':
+            toast.error('Too many attempts. Please wait.');
+            break;
+          default:
+            toast.error(error.message);
+        }
+      } else {
+        toast.error('Authentication failed');
+      }
+    } finally {
+      setIsLoading(false)
+    }
+  }
+  
+  // Add test credentials button
+  const fillTestCredentials = () => {
+    setEmail('test@example.com')
+    setPassword('Test123!')
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Sign In</CardTitle>
+        <CardDescription>
+          Enter your email and password to authenticate
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <form onSubmit={handleSubmit} className="space-y-4">
+          {/* Form fields */}
+        </form>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+## Validation Checklist
+
+✅ **Method Usage**:
+- Uses `signInWithPassword({ email, password })` with object parameter
+- NOT using separate parameters
+
+✅ **Token Management**:
+- Uses `TokenManager.storeTokens(authResponse)`
+- Calls `TokenManager.autoRefreshToken(sdk)`
+- NOT storing tokens manually in localStorage
+
+✅ **Error Handling**:
+- Imports and uses `SweetPotatoAPIError`
+- Handles `INVALID_CREDENTIALS` specifically
+- Handles `RATE_LIMITED` specifically
+- Shows user-friendly error messages
+
+✅ **UI Components**:
+- Uses shadcn/ui components (Button, Input, Card, etc.)
+- Includes loading states
+- Shows toast notifications
+
+✅ **Testing**:
+- Can login with test@example.com / Test123!
+- Tokens are stored (check DevTools > Application > Local Storage)
+- Error handling works (try wrong password)
+
+## Common Mistakes to Avoid
+
+❌ **Method signature**: `signInWithPassword(email, password)` - MUST pass object
+❌ **Token storage**: Using localStorage directly instead of TokenManager
+❌ **Missing imports**: Not importing SweetPotatoAPIError
+❌ **Generic errors**: Not handling specific error codes
+❌ **No loading state**: Form doesn't show loading indicator
+❌ **No auto-refresh**: Forgetting to call autoRefreshToken
+
+## Server Contract Note: TOTP MFA Challenge on Login
+
+If the user has activated TOTP MFA on their SPAPS account, `POST /api/auth/login`
+returns an MFA challenge payload **instead of tokens**:
+
+```json
+{ "mfa_required": true, "challenge_id": "...", "challenge": "...", "expires_at": "...", "methods": ["totp", "recovery_code"] }
+```
+
+Handle this branch before assuming tokens exist: echo `challenge_id` +
+`challenge` to `POST /api/auth/mfa/verify` together with the user's 6-digit
+TOTP code (or a single-use recovery code) to receive the standard token
+payload. Challenges expire after 300 seconds and allow at most 5 attempts.
+Accounts that never enrolled in MFA are unaffected — login returns tokens
+directly as shown above. MFA enforcement currently covers email/password
+login only (not magic-link, wallet, OIDC, WebAuthn-assertion, or SMS sign-in).
+
+## Other SPAPS Login Methods (server API)
+
+Beyond email/password (this step), wallet sign-in (step 5), and magic link
+(step 6), the SPAPS server also supports — via direct API calls; SDK helper
+coverage may lag:
+
+- **OIDC social sign-in** — `POST /api/auth/oidc/nonce` then
+  `POST /api/auth/oidc/sign-in` with a provider ID token (Google, Apple,
+  GitHub-issued OIDC). Pass the RAW nonce to the provider (hashed-nonce
+  flows are not matched). Requires the SPAPS operator to seed an
+  `auth_provider_configs` row for your application.
+- **WebAuthn passkeys** — `POST /api/auth/webauthn/register/{options,verify}`
+  (authenticated) and `POST /api/auth/webauthn/assertion/{options,verify}`
+  (sign-in).
+- **SMS OTP** — `POST /api/auth/sms/request` then `POST /api/auth/sms/verify`.
+
+All of these return the same token payload shape as `/api/auth/login`, so
+`TokenManager.storeTokens` works unchanged.
+
+## Testing Requirements
+
+1. **Successful Login**:
+   - Email: `test@example.com`
+   - Password: `Test123!`
+   - Should see success toast
+   - Tokens stored in browser
+
+2. **Failed Login**:
+   - Wrong password: Should show "Invalid credentials"
+   - Rate limiting: After 5 attempts, should show rate limit message
+
+3. **Token Verification**:
+   ```javascript
+   // In browser console:
+   const token = TokenManager.getAccessToken();
+   console.log('Token exists:', !!token);
+   ```
+
+## Next Step
+
+When ALL todos are ✅ complete and tests pass:
+
+```javascript
+mcp__product-manager__get_agent_instructions({
+  category: "spaps-integration",
+  project: "spaps-demo",
+  step: 5
+})
+```
+
+## Troubleshooting
+
+If authentication fails:
+1. Check SPAPS is running on port 3301: `curl http://localhost:3301/health`
+2. Verify SDK initialization in lib/spaps.ts
+3. Check browser console for specific errors
+4. Ensure you're using the object parameter format
+
+Remember: **The parameter format is critical!** Most failures come from using separate parameters instead of an object.