spaps-mcp 0.1.0

package/dist/wizard/step-07-payments.md

@@ -0,0 +1,529 @@
+# SPAPS Integration Step 7/12: Stripe Payment Integration
+
+## Prerequisites Check
+
+Before starting, confirm you have completed:
+- ✅ Step 1-6: Full authentication system working
+- ✅ User can login and tokens are stored
+- ✅ SDK initialized properly
+
+## Required TodoWrite List
+
+Create a TodoWrite with EXACTLY these items:
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Create payments component directory", status: "pending", activeForm: "Creating payments directory" },
+    { content: "Implement listProducts with active filter", status: "pending", activeForm: "Implementing product listing" },
+    { content: "Use createPaymentCheckout for one-time payments", status: "pending", activeForm: "Implementing payment checkout" },
+    { content: "Use createSubscriptionCheckout for subscriptions", status: "pending", activeForm: "Implementing subscription checkout" },
+    { content: "Add createCustomerPortalSession", status: "pending", activeForm: "Adding customer portal" },
+    { content: "Handle checkout URL redirects", status: "pending", activeForm: "Handling redirects" },
+    { content: "Test with amount 999 ($9.99)", status: "pending", activeForm: "Testing payments" },
+    { content: "Request step 8 of SPAPS integration wizard", status: "pending", activeForm: "Requesting next step" }
+  ]
+})
+```
+
+## Critical Method Names
+
+⚠️ **EXTREMELY IMPORTANT - CORRECT METHOD NAMES**:
+
+```typescript
+// ✅ CORRECT Methods that exist:
+sdk.payments.createPaymentCheckout()      // One-time payment
+sdk.payments.createSubscriptionCheckout()  // Subscription
+sdk.payments.listProducts()                // Get products
+sdk.payments.createCustomerPortalSession() // Customer portal
+
+// ❌ WRONG - These variations DON'T exist:
+sdk.payments.createCheckout()             // NO! Too generic
+sdk.payments.createCheckoutSession()      // NO! Different name
+sdk.payments.checkout()                   // NO! Doesn't exist
+```
+
+## Implementation Guide
+
+### 1. Payments Component
+
+```typescript
+// components/payments/stripe-payments.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 { Badge } from "@/components/ui/badge"
+import { Separator } from "@/components/ui/separator"
+import { toast } from "sonner"
+import { sdk } from '@/lib/spaps'
+import { SweetPotatoAPIError } from 'spaps-sdk'
+import { CreditCard, ShoppingCart, Settings, Loader2 } from 'lucide-react'
+
+interface Product {
+  id: string
+  name: string
+  description?: string
+  prices: Array<{
+    id: string
+    amount: number
+    currency: string
+    interval?: string  // 'month', 'year', etc.
+    intervalCount?: number
+  }>
+}
+
+export function StripePayments() {
+  const [isLoading, setIsLoading] = useState(false)
+  const [products, setProducts] = useState<Product[]>([])
+  const [loadingProducts, setLoadingProducts] = useState(true)
+
+  useEffect(() => {
+    loadProducts()
+  }, [])
+
+  const loadProducts = async () => {
+    try {
+      setLoadingProducts(true)
+      
+      // ✅ CORRECT: List products from Stripe
+      const productList = await sdk.payments.listProducts({
+        active: true,
+        limit: 10
+      })
+      
+      setProducts(productList.products || [])
+    } catch (error) {
+      if (error instanceof SweetPotatoAPIError) {
+        toast.error(`Failed to load products: ${error.message}`)
+      } else {
+        toast.error('Failed to load products')
+      }
+      console.error('Load products error:', error)
+    } finally {
+      setLoadingProducts(false)
+    }
+  }
+
+  const handleOneTimePayment = async () => {
+    setIsLoading(true)
+    try {
+      // ✅ CORRECT: Use createPaymentCheckout for one-time payments
+      const checkout = await sdk.payments.createPaymentCheckout({
+        product_name: 'Test Product',
+        amount: 999, // $9.99 in cents
+        currency: 'usd',
+        quantity: 1,
+        success_url: `${window.location.origin}/success?session_id={CHECKOUT_SESSION_ID}`,
+        cancel_url: `${window.location.origin}/cancel`,
+        metadata: {
+          userId: 'user_123',
+          source: 'demo_app'
+        }
+      })
+      
+      if (checkout.url) {
+        // Redirect to Stripe Checkout
+        window.location.href = checkout.url
+      } else {
+        toast.error('Failed to create checkout session')
+      }
+      
+    } catch (error) {
+      handlePaymentError(error)
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const handleSubscription = async (priceId: string) => {
+    setIsLoading(true)
+    try {
+      // ✅ CORRECT: Use createSubscriptionCheckout for subscriptions
+      const checkout = await sdk.payments.createSubscriptionCheckout({
+        price_id: priceId,
+        success_url: `${window.location.origin}/success?session_id={CHECKOUT_SESSION_ID}`,
+        cancel_url: `${window.location.origin}/cancel`,
+        trial_period_days: 7, // Optional trial
+        metadata: {
+          userId: 'user_123'
+        }
+      })
+      
+      if (checkout.url) {
+        window.location.href = checkout.url
+      } else {
+        toast.error('Failed to create subscription checkout')
+      }
+      
+    } catch (error) {
+      handlePaymentError(error)
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const handleCustomerPortal = async () => {
+    setIsLoading(true)
+    try {
+      // ✅ CORRECT: Create customer portal session
+      const portal = await sdk.payments.createCustomerPortalSession({
+        return_url: window.location.href
+      })
+      
+      if (portal.url) {
+        window.location.href = portal.url
+      } else {
+        toast.error('Failed to access customer portal')
+      }
+      
+    } catch (error) {
+      handlePaymentError(error)
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const handlePaymentError = (error: any) => {
+    if (error instanceof SweetPotatoAPIError) {
+      switch (error.code) {
+        case 'PAYMENT_REQUIRED':
+          toast.error('Payment required to continue')
+          break
+        case 'INSUFFICIENT_FUNDS':
+          toast.error('Payment failed: Insufficient funds')
+          break
+        case 'CARD_DECLINED':
+          toast.error('Card was declined')
+          break
+        default:
+          toast.error(error.message || 'Payment failed')
+      }
+    } else {
+      toast.error('An unexpected error occurred')
+    }
+    console.error('Payment error:', error)
+  }
+
+  const formatPrice = (amount: number, currency: string) => {
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: currency.toUpperCase(),
+    }).format(amount / 100)
+  }
+
+  return (
+    <div className="space-y-6">
+      {/* One-Time Payment */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <CreditCard className="h-5 w-5" />
+            One-Time Payment
+          </CardTitle>
+          <CardDescription>
+            Test a single payment with Stripe Checkout
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="p-4 bg-muted rounded-lg">
+            <p className="text-sm font-medium">Test Product</p>
+            <p className="text-2xl font-bold">$9.99</p>
+            <p className="text-xs text-muted-foreground">One-time payment</p>
+          </div>
+          
+          <Button 
+            onClick={handleOneTimePayment}
+            className="w-full" 
+            disabled={isLoading}
+          >
+            {isLoading ? (
+              <>
+                <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+                Processing...
+              </>
+            ) : (
+              <>
+                <ShoppingCart className="mr-2 h-4 w-4" />
+                Pay $9.99 Now
+              </>
+            )}
+          </Button>
+          
+          <p className="text-xs text-muted-foreground text-center">
+            Test card: 4242 4242 4242 4242
+          </p>
+        </CardContent>
+      </Card>
+
+      {/* Products List */}
+      <Card>
+        <CardHeader>
+          <CardTitle>Available Products</CardTitle>
+          <CardDescription>
+            Products and subscriptions from your Stripe account
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          {loadingProducts ? (
+            <div className="flex justify-center py-8">
+              <Loader2 className="h-6 w-6 animate-spin" />
+            </div>
+          ) : products.length === 0 ? (
+            <div className="text-center py-8 text-muted-foreground">
+              No products available
+            </div>
+          ) : (
+            <div className="space-y-4">
+              {products.map((product) => (
+                <div key={product.id} className="border rounded-lg p-4">
+                  <h4 className="font-medium">{product.name}</h4>
+                  {product.description && (
+                    <p className="text-sm text-muted-foreground mb-2">
+                      {product.description}
+                    </p>
+                  )}
+                  <div className="space-y-2">
+                    {product.prices.map((price) => (
+                      <div key={price.id} className="flex items-center justify-between">
+                        <div>
+                          <span className="text-sm font-medium">
+                            {formatPrice(price.amount, price.currency)}
+                          </span>
+                          {price.interval && (
+                            <span className="text-xs text-muted-foreground ml-1">
+                              / {price.interval}
+                            </span>
+                          )}
+                        </div>
+                        <Button
+                          size="sm"
+                          onClick={() => 
+                            price.interval 
+                              ? handleSubscription(price.id)
+                              : handleOneTimePayment()
+                          }
+                          disabled={isLoading}
+                        >
+                          {price.interval ? 'Subscribe' : 'Buy Now'}
+                        </Button>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              ))}
+            </div>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* Customer Portal */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <Settings className="h-5 w-5" />
+            Customer Portal
+          </CardTitle>
+          <CardDescription>
+            Manage your subscriptions and billing
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Button 
+            onClick={handleCustomerPortal}
+            className="w-full" 
+            disabled={isLoading}
+            variant="outline"
+          >
+            Open Customer Portal
+          </Button>
+          <p className="text-xs text-muted-foreground text-center mt-2">
+            View invoices, update payment methods, cancel subscriptions
+          </p>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}
+```
+
+### 2. Success/Cancel Pages
+
+Create pages to handle checkout redirects:
+
+```typescript
+// app/success/page.tsx
+'use client'
+
+import { useEffect } from 'react'
+import { useSearchParams } from 'next/navigation'
+import { Card } from "@/components/ui/card"
+import { Button } from "@/components/ui/button"
+import Link from 'next/link'
+import { CheckCircle } from 'lucide-react'
+
+export default function PaymentSuccess() {
+  const searchParams = useSearchParams()
+  const sessionId = searchParams.get('session_id')
+
+  useEffect(() => {
+    // You could verify the session here if needed
+    if (sessionId) {
+      console.log('Payment successful! Session:', sessionId)
+    }
+  }, [sessionId])
+
+  return (
+    <div className="min-h-screen flex items-center justify-center p-4">
+      <Card className="w-[400px] p-8">
+        <div className="text-center space-y-4">
+          <CheckCircle className="h-16 w-16 text-green-600 mx-auto" />
+          <h1 className="text-2xl font-bold">Payment Successful!</h1>
+          <p className="text-muted-foreground">
+            Your payment has been processed successfully.
+          </p>
+          {sessionId && (
+            <p className="text-xs text-muted-foreground font-mono">
+              Session: {sessionId.substring(0, 20)}...
+            </p>
+          )}
+          <Button asChild className="w-full">
+            <Link href="/dashboard">
+              Back to Dashboard
+            </Link>
+          </Button>
+        </div>
+      </Card>
+    </div>
+  )
+}
+```
+
+## Method Details
+
+### createPaymentCheckout
+
+For one-time payments:
+```typescript
+sdk.payments.createPaymentCheckout({
+  product_name?: string,     // Product name
+  amount?: number,           // Amount in cents
+  currency?: string,         // Currency code (usd, eur, etc.)
+  quantity?: number,         // Quantity
+  price_id?: string,         // Or use existing price ID
+  success_url: string,       // Where to redirect on success
+  cancel_url: string,        // Where to redirect on cancel
+  metadata?: Record<string, string>  // Custom metadata
+})
+```
+
+### createSubscriptionCheckout
+
+For recurring payments:
+```typescript
+sdk.payments.createSubscriptionCheckout({
+  price_id: string,          // Stripe price ID (required)
+  success_url: string,       // Where to redirect on success
+  cancel_url: string,        // Where to redirect on cancel
+  trial_period_days?: number,  // Optional trial
+  metadata?: Record<string, string>  // Custom metadata
+})
+```
+
+## Validation Checklist
+
+✅ **Method Names**:
+- Uses `createPaymentCheckout` for one-time
+- Uses `createSubscriptionCheckout` for recurring
+- NOT using generic `createCheckout`
+
+✅ **Implementation**:
+- Products load from Stripe
+- Checkout redirects work
+- Success/cancel pages exist
+- Customer portal accessible
+
+✅ **Testing**:
+- Test payment with $9.99 (999 cents)
+- Use test card: 4242 4242 4242 4242
+- Any future expiry, any CVC
+- Should redirect to Stripe
+
+## Common Mistakes to Avoid
+
+❌ **Wrong method names**:
+```typescript
+// WRONG - These don't exist
+sdk.payments.createCheckout()
+sdk.payments.checkout()
+sdk.payments.createSession()
+```
+
+❌ **Direct Stripe integration**:
+```typescript
+// WRONG - Use SDK instead
+import Stripe from 'stripe'
+const stripe = new Stripe(...)
+```
+
+❌ **Wrong amount format**:
+```typescript
+// WRONG - Amount should be in cents
+amount: 9.99  // Should be 999
+```
+
+❌ **Missing redirects**:
+```typescript
+// WRONG - Must include both URLs
+createPaymentCheckout({
+  amount: 999
+  // Missing success_url and cancel_url!
+})
+```
+
+## Testing Stripe Integration
+
+### Test Cards
+
+- **Success**: 4242 4242 4242 4242
+- **Decline**: 4000 0000 0000 0002
+- **Requires Auth**: 4000 0025 0000 3155
+
+### Local Testing
+
+In local mode:
+1. Uses Stripe test mode automatically
+2. No real charges occur
+3. Can use test cards
+4. Webhooks handled by SPAPS
+
+### Verification
+
+After payment:
+1. Check Stripe Dashboard (test mode)
+2. Verify session completed
+3. Check user's payment status
+4. Test customer portal access
+
+## Next Step
+
+When ALL todos are ✅ complete and payments work:
+
+```javascript
+mcp__product-manager__get_agent_instructions({
+  category: "spaps-integration",
+  project: "spaps-demo",
+  step: 8
+})
+```
+
+## Summary
+
+Stripe integration via SDK provides:
+- **Simple checkout** - Just redirect to Stripe
+- **Secure payments** - PCI compliance handled
+- **Subscriptions** - Recurring payments supported
+- **Customer portal** - Self-service management
+
+Remember: Use the EXACT method names - this is where most errors occur!