spaps 0.2.4 → 0.2.6

package/bin/spaps.js

@@ -13,6 +13,8 @@ const { spawn } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const { handleError } = require('../src/error-handler');
+const { showInteractiveHelp, showQuickHelp } = require('../src/help-system');
+const { showInteractiveDocs, showQuickReference, searchDocs } = require('../src/docs-system');
 
 const version = require('../package.json').version;
 
@@ -176,6 +178,60 @@ program
     console.log(chalk.yellow(`🚧 'spaps types' coming in v0.4.0!`));
   });
 
+// Help command - Interactive help system
+program
+  .command('help')
+  .description('Show help and guides')
+  .option('-i, --interactive', 'Interactive help mode')
+  .option('-q, --quick', 'Quick reference')
+  .action(async (options) => {
+    if (options.interactive) {
+      await showInteractiveHelp();
+    } else if (options.quick) {
+      showQuickHelp();
+    } else {
+      // Default to quick help
+      showQuickHelp();
+    }
+  });
+
+// Docs command - SDK documentation
+program
+  .command('docs')
+  .description('Browse SDK documentation')
+  .option('-i, --interactive', 'Interactive documentation browser')
+  .option('-s, --search <query>', 'Search documentation')
+  .option('--json', 'Output in JSON format')
+  .action(async (options) => {
+    if (options.search) {
+      const results = searchDocs(options.search);
+      
+      if (options.json) {
+        console.log(JSON.stringify({ results }, null, 2));
+      } else {
+        console.log(chalk.yellow(`\n🔍 Search results for "${options.search}":\n`));
+        
+        if (results.length === 0) {
+          console.log(chalk.gray('  No results found'));
+        } else {
+          results.forEach((result, i) => {
+            console.log(chalk.green(`  ${i + 1}. ${result.title}`));
+            console.log(chalk.gray(`     ${result.preview}`));
+            console.log();
+          });
+        }
+        
+        console.log(chalk.blue('  Run: npx spaps docs --interactive'));
+        console.log(chalk.blue('  to browse full documentation\n'));
+      }
+    } else if (options.interactive) {
+      await showInteractiveDocs();
+    } else {
+      // Default to quick reference
+      showQuickReference();
+    }
+  });
+
 // Help command enhancement
 program.on('--help', () => {
   console.log();
@@ -192,6 +248,8 @@ program.on('--help', () => {
 if (!process.argv.slice(2).length) {
   console.log(logo);
   program.outputHelp();
+  console.log();
+  console.log(chalk.yellow('💡 Try: npx spaps help --interactive'));
 }
 
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Sweet Potato Authentication & Payment Service CLI - Zero-config local development and project scaffolding",
   "main": "bin/spaps.js",
   "bin": {

package/src/docs-system.js

@@ -0,0 +1,806 @@
+/**
+ * SPAPS CLI Documentation System
+ * Comprehensive SDK and API documentation
+ */
+
+const chalk = require('chalk');
+const prompts = require('prompts');
+
+const SDK_DOCS = {
+  quickstart: {
+    title: 'SDK Quick Start',
+    content: `
+${chalk.green('Installation:')}
+  npm install spaps-sdk
+  # or
+  yarn add spaps-sdk
+
+${chalk.green('Basic Usage:')}
+  ${chalk.gray('// ES6 Import')}
+  import { SPAPSClient } from 'spaps-sdk'
+  
+  ${chalk.gray('// CommonJS')}
+  const { SPAPSClient } = require('spaps-sdk')
+  
+  ${chalk.gray('// Create client (auto-detects local mode)')}
+  const spaps = new SPAPSClient()
+  
+  ${chalk.gray('// With custom config')}
+  const spaps = new SPAPSClient({
+    apiUrl: 'http://localhost:3300',
+    apiKey: 'your-api-key',  ${chalk.gray('// Not needed for localhost')}
+    timeout: 10000
+  })
+`
+  },
+
+  authentication: {
+    title: 'Authentication Methods',
+    content: `
+${chalk.green('Email/Password Authentication:')}
+  ${chalk.gray('// Register new user')}
+  const { data } = await spaps.register(email, password)
+  console.log('User:', data.user)
+  console.log('Token:', data.access_token)
+  
+  ${chalk.gray('// Login existing user')}
+  const { data } = await spaps.login(email, password)
+  
+  ${chalk.gray('// Check authentication status')}
+  if (spaps.isAuthenticated()) {
+    const user = await spaps.getUser()
+    console.log('Current user:', user.data)
+  }
+  
+  ${chalk.gray('// Logout')}
+  await spaps.logout()
+
+${chalk.green('Wallet Authentication:')}
+  ${chalk.gray('// Solana wallet')}
+  await spaps.walletSignIn(
+    walletAddress,
+    signature,
+    message,
+    'solana'
+  )
+  
+  ${chalk.gray('// Ethereum wallet')}
+  await spaps.walletSignIn(
+    walletAddress,
+    signature,
+    message,
+    'ethereum'
+  )
+
+${chalk.green('Token Management:')}
+  ${chalk.gray('// Get current token')}
+  const token = spaps.getAccessToken()
+  
+  ${chalk.gray('// Set token manually')}
+  spaps.setAccessToken(token)
+  
+  ${chalk.gray('// Refresh token')}
+  await spaps.refresh()
+`
+  },
+
+  payments: {
+    title: 'Payment Integration',
+    content: `
+${chalk.green('Stripe Checkout:')}
+  ${chalk.gray('// Create checkout session')}
+  const session = await spaps.createCheckoutSession(
+    'price_123abc',           ${chalk.gray('// Stripe price ID')}
+    'http://localhost:3000/success',  ${chalk.gray('// Success URL')}
+    'http://localhost:3000/cancel'    ${chalk.gray('// Cancel URL (optional)')}
+  )
+  
+  ${chalk.gray('// Redirect to Stripe')}
+  window.location.href = session.data.url
+
+${chalk.green('Subscription Management:')}
+  ${chalk.gray('// Get current subscription')}
+  const subscription = await spaps.getSubscription()
+  console.log('Status:', subscription.data.status)
+  console.log('Plan:', subscription.data.plan)
+  console.log('Renews:', subscription.data.current_period_end)
+  
+  ${chalk.gray('// Cancel subscription')}
+  await spaps.cancelSubscription()
+
+${chalk.green('Usage Tracking:')}
+  ${chalk.gray('// Check balance')}
+  const balance = await spaps.getUsageBalance()
+  console.log('Credits:', balance.data.balance)
+  
+  ${chalk.gray('// Record usage')}
+  await spaps.recordUsage('api-call', 1)
+  await spaps.recordUsage('image-generation', 10)
+`
+  },
+
+  config: {
+    title: 'Configuration',
+    content: `
+${chalk.green('Environment Variables:')}
+  ${chalk.gray('# .env or .env.local')}
+  SPAPS_API_URL=http://localhost:3300
+  SPAPS_API_KEY=spaps_live_abc123...
+  
+  ${chalk.gray('# Next.js (use NEXT_PUBLIC_ prefix)')}
+  NEXT_PUBLIC_SPAPS_API_URL=http://localhost:3300
+  NEXT_PUBLIC_SPAPS_API_KEY=spaps_live_abc123...
+
+${chalk.green('Configuration Options:')}
+  const spaps = new SPAPSClient({
+    ${chalk.gray('// API endpoint (auto-detected from env)')}
+    apiUrl: 'http://localhost:3300',
+    
+    ${chalk.gray('// API key (not needed for localhost)')}
+    apiKey: 'spaps_live_abc123...',
+    
+    ${chalk.gray('// Request timeout in milliseconds')}
+    timeout: 10000,
+    
+    ${chalk.gray('// Auto-detect local mode (default: true)')}
+    autoDetect: true
+  })
+
+${chalk.green('Local Mode Detection:')}
+  ${chalk.gray('// The SDK automatically detects local mode when:')}
+  - URL contains 'localhost'
+  - URL contains '127.0.0.1'
+  - No API URL is provided
+  
+  ${chalk.gray('// Check if in local mode')}
+  if (spaps.isLocalMode()) {
+    console.log('Running in local mode - no API key needed!')
+  }
+`
+  },
+
+  react: {
+    title: 'React Integration',
+    content: `
+${chalk.green('React Context Setup:')}
+  ${chalk.gray('// contexts/SpapsContext.tsx')}
+  import { createContext, useContext } from 'react'
+  import { SPAPSClient } from 'spaps-sdk'
+  
+  const spaps = new SPAPSClient()
+  const SpapsContext = createContext(spaps)
+  
+  export function SpapsProvider({ children }) {
+    return (
+      <SpapsContext.Provider value={spaps}>
+        {children}
+      </SpapsContext.Provider>
+    )
+  }
+  
+  export const useSpaps = () => useContext(SpapsContext)
+
+${chalk.green('React Hook Example:')}
+  ${chalk.gray('// hooks/useAuth.ts')}
+  import { useState, useEffect } from 'react'
+  import { useSpaps } from '../contexts/SpapsContext'
+  
+  export function useAuth() {
+    const spaps = useSpaps()
+    const [user, setUser] = useState(null)
+    const [loading, setLoading] = useState(true)
+    
+    useEffect(() => {
+      if (spaps.isAuthenticated()) {
+        spaps.getUser()
+          .then(res => setUser(res.data))
+          .finally(() => setLoading(false))
+      } else {
+        setLoading(false)
+      }
+    }, [])
+    
+    return { user, loading, isAuthenticated: !!user }
+  }
+
+${chalk.green('Component Example:')}
+  ${chalk.gray('// components/LoginForm.tsx')}
+  function LoginForm() {
+    const spaps = useSpaps()
+    const [email, setEmail] = useState('')
+    const [password, setPassword] = useState('')
+    
+    const handleSubmit = async (e) => {
+      e.preventDefault()
+      try {
+        await spaps.login(email, password)
+        // Redirect or update state
+      } catch (error) {
+        console.error('Login failed:', error)
+      }
+    }
+    
+    return (
+      <form onSubmit={handleSubmit}>
+        <input 
+          type="email" 
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+        />
+        <input 
+          type="password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+        />
+        <button type="submit">Login</button>
+      </form>
+    )
+  }
+`
+  },
+
+  nextjs: {
+    title: 'Next.js Integration',
+    content: `
+${chalk.green('App Router Setup:')}
+  ${chalk.gray('// app/providers.tsx')}
+  'use client'
+  
+  import { SPAPSClient } from 'spaps-sdk'
+  import { createContext, useContext } from 'react'
+  
+  const SpapsContext = createContext<SPAPSClient | null>(null)
+  
+  export function Providers({ children }) {
+    const spaps = new SPAPSClient({
+      apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL
+    })
+    
+    return (
+      <SpapsContext.Provider value={spaps}>
+        {children}
+      </SpapsContext.Provider>
+    )
+  }
+  
+  export const useSpaps = () => {
+    const context = useContext(SpapsContext)
+    if (!context) throw new Error('Missing SpapsProvider')
+    return context
+  }
+
+${chalk.green('Server Actions:')}
+  ${chalk.gray('// app/actions/auth.ts')}
+  'use server'
+  
+  import { SPAPSClient } from 'spaps-sdk'
+  import { cookies } from 'next/headers'
+  
+  const spaps = new SPAPSClient({
+    apiUrl: process.env.SPAPS_API_URL,
+    apiKey: process.env.SPAPS_API_KEY
+  })
+  
+  export async function loginAction(email: string, password: string) {
+    const { data } = await spaps.login(email, password)
+    
+    // Store token in cookie
+    cookies().set('spaps_token', data.access_token, {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'lax',
+      maxAge: 60 * 60 * 24 * 7 // 1 week
+    })
+    
+    return { success: true, user: data.user }
+  }
+
+${chalk.green('Middleware Protection:')}
+  ${chalk.gray('// middleware.ts')}
+  import { NextResponse } from 'next/server'
+  import type { NextRequest } from 'next/server'
+  
+  export function middleware(request: NextRequest) {
+    const token = request.cookies.get('spaps_token')
+    
+    if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+      return NextResponse.redirect(new URL('/login', request.url))
+    }
+    
+    return NextResponse.next()
+  }
+  
+  export const config = {
+    matcher: '/dashboard/:path*'
+  }
+`
+  },
+
+  nodejs: {
+    title: 'Node.js/Express Integration',
+    content: `
+${chalk.green('Express Middleware:')}
+  ${chalk.gray('// server.js')}
+  const express = require('express')
+  const { SPAPSClient } = require('spaps-sdk')
+  
+  const app = express()
+  const spaps = new SPAPSClient({
+    apiUrl: process.env.SPAPS_API_URL,
+    apiKey: process.env.SPAPS_API_KEY
+  })
+  
+  ${chalk.gray('// Add SPAPS to request')}
+  app.use((req, res, next) => {
+    req.spaps = spaps
+    next()
+  })
+  
+  ${chalk.gray('// Auth middleware')}
+  async function requireAuth(req, res, next) {
+    const token = req.headers.authorization?.split(' ')[1]
+    
+    if (!token) {
+      return res.status(401).json({ error: 'No token provided' })
+    }
+    
+    try {
+      req.spaps.setAccessToken(token)
+      const { data } = await req.spaps.getUser()
+      req.user = data
+      next()
+    } catch (error) {
+      res.status(401).json({ error: 'Invalid token' })
+    }
+  }
+
+${chalk.green('Route Examples:')}
+  ${chalk.gray('// Login endpoint')}
+  app.post('/api/login', async (req, res) => {
+    const { email, password } = req.body
+    
+    try {
+      const { data } = await req.spaps.login(email, password)
+      res.json(data)
+    } catch (error) {
+      res.status(401).json({ error: 'Invalid credentials' })
+    }
+  })
+  
+  ${chalk.gray('// Protected route')}
+  app.get('/api/profile', requireAuth, (req, res) => {
+    res.json(req.user)
+  })
+  
+  ${chalk.gray('// Stripe webhook')}
+  app.post('/api/webhooks/stripe', async (req, res) => {
+    // Verify webhook signature
+    // Update user subscription status
+    res.json({ received: true })
+  })
+`
+  },
+
+  errors: {
+    title: 'Error Handling',
+    content: `
+${chalk.green('Error Types:')}
+  try {
+    await spaps.login(email, password)
+  } catch (error) {
+    if (error.response) {
+      ${chalk.gray('// Server responded with error')}
+      console.log('Status:', error.response.status)
+      console.log('Data:', error.response.data)
+      
+      switch (error.response.status) {
+        case 401:
+          console.error('Invalid credentials')
+          break
+        case 429:
+          console.error('Rate limited - try again later')
+          break
+        case 500:
+          console.error('Server error')
+          break
+      }
+    } else if (error.request) {
+      ${chalk.gray('// Request made but no response')}
+      console.error('Network error - server unreachable')
+    } else {
+      ${chalk.gray('// Error in request setup')}
+      console.error('Request error:', error.message)
+    }
+  }
+
+${chalk.green('Custom Error Handling:')}
+  ${chalk.gray('// Global error handler')}
+  spaps.client.interceptors.response.use(
+    response => response,
+    error => {
+      if (error.response?.status === 401) {
+        // Token expired - redirect to login
+        window.location.href = '/login'
+      }
+      return Promise.reject(error)
+    }
+  )
+
+${chalk.green('Retry Logic:')}
+  ${chalk.gray('// Retry failed requests')}
+  async function retryRequest(fn, retries = 3) {
+    try {
+      return await fn()
+    } catch (error) {
+      if (retries > 0 && error.response?.status >= 500) {
+        await new Promise(r => setTimeout(r, 1000))
+        return retryRequest(fn, retries - 1)
+      }
+      throw error
+    }
+  }
+  
+  ${chalk.gray('// Usage')}
+  const user = await retryRequest(() => spaps.getUser())
+`
+  },
+
+  typescript: {
+    title: 'TypeScript Support',
+    content: `
+${chalk.green('Type Definitions:')}
+  import { 
+    SPAPSClient,
+    SPAPSConfig,
+    AuthResponse,
+    User,
+    CheckoutSession,
+    Subscription,
+    UsageBalance
+  } from 'spaps-sdk'
+
+${chalk.green('Interface Examples:')}
+  ${chalk.gray('// User type')}
+  interface User {
+    id: string
+    email?: string
+    wallet_address?: string
+    chain_type?: string
+    role: string
+    created_at?: string
+  }
+  
+  ${chalk.gray('// Auth response')}
+  interface AuthResponse {
+    access_token: string
+    refresh_token: string
+    user: User
+  }
+  
+  ${chalk.gray('// Config options')}
+  interface SPAPSConfig {
+    apiUrl?: string
+    apiKey?: string
+    autoDetect?: boolean
+    timeout?: number
+  }
+
+${chalk.green('Type-Safe Usage:')}
+  ${chalk.gray('// Typed client')}
+  const spaps: SPAPSClient = new SPAPSClient({
+    apiUrl: 'http://localhost:3300'
+  })
+  
+  ${chalk.gray('// Typed responses')}
+  const login = async (email: string, password: string): Promise<User> => {
+    const { data }: { data: AuthResponse } = await spaps.login(email, password)
+    return data.user
+  }
+  
+  ${chalk.gray('// Generic wrapper')}
+  async function apiCall<T>(
+    fn: () => Promise<{ data: T }>
+  ): Promise<T> {
+    try {
+      const { data } = await fn()
+      return data
+    } catch (error) {
+      console.error('API call failed:', error)
+      throw error
+    }
+  }
+  
+  ${chalk.gray('// Usage')}
+  const user = await apiCall<User>(() => spaps.getUser())
+`
+  },
+
+  testing: {
+    title: 'Testing',
+    content: `
+${chalk.green('Unit Testing with Jest:')}
+  ${chalk.gray('// __tests__/auth.test.js')}
+  import { SPAPSClient } from 'spaps-sdk'
+  
+  describe('Authentication', () => {
+    let spaps
+    
+    beforeEach(() => {
+      spaps = new SPAPSClient({
+        apiUrl: 'http://localhost:3300'
+      })
+    })
+    
+    test('login returns user and token', async () => {
+      const { data } = await spaps.login('test@example.com', 'password')
+      
+      expect(data.user).toBeDefined()
+      expect(data.user.email).toBe('test@example.com')
+      expect(data.access_token).toBeDefined()
+    })
+    
+    test('sets auth token after login', async () => {
+      await spaps.login('test@example.com', 'password')
+      
+      expect(spaps.isAuthenticated()).toBe(true)
+      expect(spaps.getAccessToken()).toBeDefined()
+    })
+  })
+
+${chalk.green('E2E Testing with Cypress:')}
+  ${chalk.gray('// cypress/e2e/auth.cy.js')}
+  describe('Auth Flow', () => {
+    beforeEach(() => {
+      cy.visit('http://localhost:3000')
+    })
+    
+    it('allows user to login', () => {
+      cy.get('[data-cy=email]').type('test@example.com')
+      cy.get('[data-cy=password]').type('password')
+      cy.get('[data-cy=submit]').click()
+      
+      cy.url().should('include', '/dashboard')
+      cy.contains('Welcome back')
+    })
+  })
+
+${chalk.green('Mocking for Tests:')}
+  ${chalk.gray('// Mock SPAPS client')}
+  jest.mock('spaps-sdk', () => ({
+    SPAPSClient: jest.fn().mockImplementation(() => ({
+      login: jest.fn().mockResolvedValue({
+        data: {
+          user: { id: '123', email: 'test@example.com' },
+          access_token: 'mock-token'
+        }
+      }),
+      isAuthenticated: jest.fn().mockReturnValue(true),
+      getUser: jest.fn().mockResolvedValue({
+        data: { id: '123', email: 'test@example.com' }
+      })
+    }))
+  }))
+`
+  },
+
+  api_reference: {
+    title: 'API Reference',
+    content: `
+${chalk.green('Authentication Methods:')}
+  login(email: string, password: string): Promise<{data: AuthResponse}>
+  register(email: string, password: string): Promise<{data: AuthResponse}>
+  walletSignIn(address: string, signature: string, message: string, chain: string): Promise<{data: AuthResponse}>
+  refresh(refreshToken?: string): Promise<{data: AuthResponse}>
+  logout(): Promise<void>
+  getUser(): Promise<{data: User}>
+
+${chalk.green('Payment Methods:')}
+  createCheckoutSession(priceId: string, successUrl: string, cancelUrl?: string): Promise<{data: CheckoutSession}>
+  getSubscription(): Promise<{data: Subscription}>
+  cancelSubscription(): Promise<void>
+
+${chalk.green('Usage Methods:')}
+  getUsageBalance(): Promise<{data: UsageBalance}>
+  recordUsage(feature: string, amount: number): Promise<void>
+
+${chalk.green('Utility Methods:')}
+  isAuthenticated(): boolean
+  getAccessToken(): string | undefined
+  setAccessToken(token: string): void
+  isLocalMode(): boolean
+  health(): Promise<{data: any}>
+
+${chalk.green('Properties:')}
+  client: AxiosInstance  ${chalk.gray('// Direct access to Axios client')}
+
+${chalk.green('Response Types:')}
+  ${chalk.gray('// All methods return data wrapped in { data: T }')}
+  ${chalk.gray('// This matches Axios response structure')}
+  ${chalk.gray('// Example:')}
+  const response = await spaps.login(email, password)
+  // response.data contains AuthResponse
+  // response.status, response.headers also available
+`
+  }
+};
+
+const API_ENDPOINTS = {
+  title: 'API Endpoints',
+  content: `
+${chalk.green('Authentication Endpoints:')}
+  POST   /api/auth/register        ${chalk.gray('Register new user')}
+  POST   /api/auth/login           ${chalk.gray('Login with email/password')}
+  POST   /api/auth/wallet-sign-in  ${chalk.gray('Login with wallet')}
+  POST   /api/auth/refresh          ${chalk.gray('Refresh access token')}
+  POST   /api/auth/logout           ${chalk.gray('Logout user')}
+  GET    /api/auth/user             ${chalk.gray('Get current user')}
+
+${chalk.green('Stripe Endpoints:')}
+  POST   /api/stripe/create-checkout-session  ${chalk.gray('Create Stripe checkout')}
+  GET    /api/stripe/subscription             ${chalk.gray('Get subscription status')}
+  DELETE /api/stripe/subscription             ${chalk.gray('Cancel subscription')}
+  POST   /api/stripe/webhook                  ${chalk.gray('Stripe webhook handler')}
+
+${chalk.green('Usage Endpoints:')}
+  GET    /api/usage/balance         ${chalk.gray('Get usage balance')}
+  POST   /api/usage/record          ${chalk.gray('Record usage event')}
+  GET    /api/usage/history         ${chalk.gray('Get usage history')}
+
+${chalk.green('Health Endpoints:')}
+  GET    /health                    ${chalk.gray('Health check')}
+  GET    /health/local-mode         ${chalk.gray('Local mode status')}
+
+${chalk.green('Local Mode Features:')}
+  ${chalk.gray('In local mode (http://localhost:3300):')}
+  • No API key required
+  • Auto-authentication enabled
+  • CORS disabled for all origins
+  • Mock responses for all endpoints
+  • Test users available: user, admin, premium
+`
+};
+
+async function showDocsMenu() {
+  const choices = [
+    { title: '🚀 Quick Start', value: 'quickstart' },
+    { title: '🔐 Authentication', value: 'authentication' },
+    { title: '💳 Payments', value: 'payments' },
+    { title: '⚙️ Configuration', value: 'config' },
+    { title: '⚛️ React Integration', value: 'react' },
+    { title: '▲ Next.js Integration', value: 'nextjs' },
+    { title: '🟢 Node.js/Express', value: 'nodejs' },
+    { title: '❌ Error Handling', value: 'errors' },
+    { title: '📘 TypeScript', value: 'typescript' },
+    { title: '🧪 Testing', value: 'testing' },
+    { title: '📖 API Reference', value: 'api_reference' },
+    { title: '🌐 API Endpoints', value: 'endpoints' },
+    { title: chalk.gray('← Back'), value: '__back__' },
+    { title: chalk.gray('✕ Exit'), value: '__exit__' }
+  ];
+
+  const response = await prompts({
+    type: 'select',
+    name: 'section',
+    message: 'Select documentation section:',
+    choices: choices
+  });
+
+  return response.section;
+}
+
+async function showInteractiveDocs() {
+  console.log(chalk.yellow('\n🍠 SPAPS SDK Documentation\n'));
+  
+  while (true) {
+    const section = await showDocsMenu();
+    
+    if (!section || section === '__exit__') {
+      console.log(chalk.gray('\nGoodbye! 👋\n'));
+      process.exit(0);
+    }
+    
+    if (section === '__back__') {
+      return; // Go back to main help
+    }
+    
+    if (section === 'endpoints') {
+      console.log(chalk.yellow(`\n${API_ENDPOINTS.title}`));
+      console.log(API_ENDPOINTS.content);
+    } else if (SDK_DOCS[section]) {
+      const doc = SDK_DOCS[section];
+      console.log(chalk.yellow(`\n${doc.title}`));
+      console.log(doc.content);
+    }
+    
+    // Wait for user to read
+    const cont = await prompts({
+      type: 'confirm',
+      name: 'continue',
+      message: 'Continue browsing docs?',
+      initial: true
+    });
+    
+    if (!cont.continue) {
+      console.log(chalk.gray('\nGoodbye! 👋\n'));
+      process.exit(0);
+    }
+  }
+}
+
+function showQuickReference() {
+  console.log(chalk.yellow('\n🍠 SPAPS SDK Quick Reference\n'));
+  
+  console.log(chalk.green('Installation:'));
+  console.log('  npm install spaps-sdk');
+  console.log();
+  
+  console.log(chalk.green('Basic Setup:'));
+  console.log(chalk.gray(`  import { SPAPSClient } from 'spaps-sdk'`));
+  console.log(chalk.gray(`  const spaps = new SPAPSClient()`));
+  console.log();
+  
+  console.log(chalk.green('Common Methods:'));
+  console.log('  await spaps.login(email, password)');
+  console.log('  await spaps.register(email, password)');
+  console.log('  await spaps.getUser()');
+  console.log('  await spaps.createCheckoutSession(priceId, successUrl)');
+  console.log('  await spaps.getSubscription()');
+  console.log('  await spaps.getUsageBalance()');
+  console.log();
+  
+  console.log(chalk.green('Helper Methods:'));
+  console.log('  spaps.isAuthenticated()  ' + chalk.gray('// Check auth status'));
+  console.log('  spaps.isLocalMode()       ' + chalk.gray('// Check if local mode'));
+  console.log('  spaps.getAccessToken()    ' + chalk.gray('// Get current token'));
+  console.log();
+  
+  console.log(chalk.blue('📚 Full docs: npx spaps docs --interactive'));
+  console.log();
+}
+
+function searchDocs(query) {
+  const results = [];
+  const searchTerm = query.toLowerCase();
+  
+  // Search through all documentation
+  Object.entries(SDK_DOCS).forEach(([key, doc]) => {
+    const content = doc.content.toLowerCase();
+    const title = doc.title.toLowerCase();
+    
+    if (title.includes(searchTerm) || content.includes(searchTerm)) {
+      // Count occurrences
+      const titleMatches = (title.match(new RegExp(searchTerm, 'g')) || []).length;
+      const contentMatches = (content.match(new RegExp(searchTerm, 'g')) || []).length;
+      
+      results.push({
+        section: key,
+        title: doc.title,
+        score: titleMatches * 10 + contentMatches,
+        preview: extractPreview(doc.content, searchTerm)
+      });
+    }
+  });
+  
+  // Sort by relevance
+  results.sort((a, b) => b.score - a.score);
+  
+  return results.slice(0, 5); // Top 5 results
+}
+
+function extractPreview(content, searchTerm) {
+  const lines = content.split('\n');
+  for (const line of lines) {
+    if (line.toLowerCase().includes(searchTerm)) {
+      return line.trim().substring(0, 80) + '...';
+    }
+  }
+  return lines[0].trim().substring(0, 80) + '...';
+}
+
+module.exports = {
+  showInteractiveDocs,
+  showQuickReference,
+  searchDocs,
+  SDK_DOCS,
+  API_ENDPOINTS
+};

package/src/help-system.js

@@ -0,0 +1,487 @@
+/**
+ * SPAPS CLI Interactive Help System
+ * Decision trees and structured guidance for developers
+ */
+
+const chalk = require('chalk');
+const prompts = require('prompts');
+
+const HELP_TREE = {
+  root: {
+    question: 'What would you like to do?',
+    options: [
+      {
+        title: '🚀 Start developing locally',
+        value: 'local-dev',
+        description: 'Run SPAPS on your machine'
+      },
+      {
+        title: '📦 Set up a new project',
+        value: 'new-project',
+        description: 'Create a new app with SPAPS'
+      },
+      {
+        title: '🔧 Add SPAPS to existing project',
+        value: 'existing-project',
+        description: 'Integrate SPAPS into your app'
+      },
+      {
+        title: '🐛 Debug an issue',
+        value: 'debug',
+        description: 'Troubleshoot problems'
+      },
+      {
+        title: '📚 Learn about SPAPS',
+        value: 'learn',
+        description: 'Understand concepts and features'
+      }
+    ]
+  },
+
+  'local-dev': {
+    question: 'How do you want to run SPAPS locally?',
+    options: [
+      {
+        title: 'Quick start (default settings)',
+        value: 'quick-start',
+        command: 'npx spaps local',
+        description: 'Start on port 3300'
+      },
+      {
+        title: 'Custom port',
+        value: 'custom-port',
+        command: 'npx spaps local --port 3001',
+        description: 'Choose your own port'
+      },
+      {
+        title: 'Open browser automatically',
+        value: 'auto-open',
+        command: 'npx spaps local --open',
+        description: 'Opens docs in browser'
+      },
+      {
+        title: 'JSON mode (for CI/CD)',
+        value: 'json-mode',
+        command: 'npx spaps local --json',
+        description: 'Machine-readable output'
+      }
+    ]
+  },
+
+  'new-project': {
+    question: 'What type of project?',
+    options: [
+      {
+        title: 'Next.js App',
+        value: 'nextjs',
+        command: 'npx spaps create my-app --template nextjs',
+        description: 'Full-stack React framework',
+        available: 'v0.3.0'
+      },
+      {
+        title: 'React + Vite',
+        value: 'react',
+        command: 'npx spaps create my-app --template react',
+        description: 'Fast, modern React setup',
+        available: 'v0.3.0'
+      },
+      {
+        title: 'Node.js API',
+        value: 'node',
+        command: 'npx spaps create my-api --template node',
+        description: 'Express.js backend',
+        available: 'v0.3.0'
+      },
+      {
+        title: 'Vanilla JavaScript',
+        value: 'vanilla',
+        command: 'npx spaps create my-app --template vanilla',
+        description: 'No framework, just JS',
+        available: 'v0.3.0'
+      }
+    ]
+  },
+
+  'existing-project': {
+    question: 'What framework are you using?',
+    options: [
+      {
+        title: 'Next.js',
+        value: 'integrate-nextjs',
+        steps: [
+          'npm install spaps-sdk',
+          'npx spaps init',
+          'Add to your app:',
+          '',
+          '// app/providers.tsx',
+          'import { SPAPSClient } from "spaps-sdk"',
+          'const spaps = new SPAPSClient()'
+        ]
+      },
+      {
+        title: 'React',
+        value: 'integrate-react',
+        steps: [
+          'npm install spaps-sdk',
+          'npx spaps init',
+          'Create a context:',
+          '',
+          '// src/contexts/SpapsContext.tsx',
+          'import { SPAPSClient } from "spaps-sdk"',
+          'const spaps = new SPAPSClient()',
+          'export const SpapsContext = React.createContext(spaps)'
+        ]
+      },
+      {
+        title: 'Node.js/Express',
+        value: 'integrate-node',
+        steps: [
+          'npm install spaps-sdk',
+          'npx spaps init',
+          'Add middleware:',
+          '',
+          '// server.js',
+          'const { SPAPSClient } = require("spaps-sdk")',
+          'const spaps = new SPAPSClient()',
+          '',
+          'app.use(async (req, res, next) => {',
+          '  req.spaps = spaps',
+          '  next()',
+          '})'
+        ]
+      },
+      {
+        title: 'Other/Vanilla',
+        value: 'integrate-other',
+        steps: [
+          'npm install spaps-sdk',
+          'npx spaps init',
+          'Import in your code:',
+          '',
+          '// Using ES6 modules',
+          'import { SPAPSClient } from "spaps-sdk"',
+          '',
+          '// Using CommonJS',
+          'const { SPAPSClient } = require("spaps-sdk")',
+          '',
+          '// Using CDN',
+          '<script src="https://unpkg.com/spaps-sdk"></script>'
+        ]
+      }
+    ]
+  },
+
+  'debug': {
+    question: 'What issue are you experiencing?',
+    options: [
+      {
+        title: 'Port already in use',
+        value: 'port-error',
+        solution: {
+          commands: [
+            'npx spaps local --port 3301',
+            'lsof -ti:3300 | xargs kill -9',
+            'npx spaps local --port 0'
+          ],
+          explanation: 'Another process is using port 3300. Either use a different port or kill the existing process.'
+        }
+      },
+      {
+        title: 'Module not found',
+        value: 'module-error',
+        solution: {
+          commands: [
+            'npm install',
+            'rm -rf node_modules package-lock.json && npm install',
+            'npm install spaps-sdk'
+          ],
+          explanation: 'Dependencies are missing. Reinstall packages to fix this.'
+        }
+      },
+      {
+        title: 'CORS errors',
+        value: 'cors-error',
+        solution: {
+          commands: [
+            'npx spaps local',
+            'Check your API URL: process.env.SPAPS_API_URL'
+          ],
+          explanation: 'CORS is automatically handled in local mode. Make sure your client is pointing to the local server.'
+        }
+      },
+      {
+        title: 'Authentication failing',
+        value: 'auth-error',
+        solution: {
+          commands: [
+            'curl http://localhost:3300/health',
+            'npx spaps local --port 3300'
+          ],
+          explanation: 'In local mode, authentication is automatic. Make sure the local server is running.'
+        }
+      }
+    ]
+  },
+
+  'learn': {
+    question: 'What would you like to learn about?',
+    options: [
+      {
+        title: 'How SPAPS works',
+        value: 'how-it-works',
+        content: `
+SPAPS (Sweet Potato Authentication & Payment Service) provides:
+
+1. **Authentication**: Email/password, magic links, and wallet-based auth
+2. **Payments**: Stripe subscriptions and wallet-based payments
+3. **Local Development**: Zero-config local mode with auto-auth
+4. **Type Safety**: Full TypeScript support with generated types
+5. **Multi-tenant**: API key-based app isolation
+
+In local mode, everything is mocked so you can develop without:
+- API keys
+- Database setup
+- External services
+- Configuration files
+        `
+      },
+      {
+        title: 'Local vs Production',
+        value: 'environments',
+        content: `
+**Local Mode** (http://localhost:3300):
+- No API key required
+- Auto-authentication
+- Mocked responses
+- CORS disabled
+- Perfect for development
+
+**Production Mode** (https://api.yourapp.com):
+- API key required
+- Real authentication
+- Database persistence
+- Stripe integration
+- Rate limiting
+
+The SDK auto-detects which mode to use based on the URL!
+        `
+      },
+      {
+        title: 'Authentication methods',
+        value: 'auth-methods',
+        content: `
+SPAPS supports multiple authentication methods:
+
+**Traditional Auth**:
+- Email/password login
+- Magic link (passwordless)
+- Social logins (coming soon)
+
+**Wallet Auth**:
+- Solana wallets
+- Ethereum wallets
+- Bitcoin (coming soon)
+- Base chain (coming soon)
+
+**Code Examples**:
+\`\`\`javascript
+// Email/password
+await spaps.login(email, password)
+
+// Wallet
+await spaps.walletSignIn(address, signature, message, 'solana')
+\`\`\`
+        `
+      },
+      {
+        title: 'Payment integration',
+        value: 'payments',
+        content: `
+SPAPS handles two payment types:
+
+**Stripe Subscriptions**:
+- Monthly/annual plans
+- Usage-based billing
+- Customer portal
+- Webhook handling
+
+**Wallet Payments**:
+- Direct crypto payments
+- Usage credits
+- Instant settlement
+- Multi-chain support
+
+**Code Example**:
+\`\`\`javascript
+// Create Stripe checkout
+const session = await spaps.createCheckoutSession(priceId, successUrl)
+
+// Check subscription
+const sub = await spaps.getSubscription()
+\`\`\`
+        `
+      }
+    ]
+  }
+};
+
+async function showInteractiveHelp() {
+  console.log(chalk.yellow('\n🍠 SPAPS Interactive Help\n'));
+  
+  let currentNode = 'root';
+  const history = [];
+  
+  while (true) {
+    const node = HELP_TREE[currentNode];
+    
+    if (!node) {
+      // Leaf node - show result
+      break;
+    }
+    
+    const choices = node.options.map(opt => ({
+      title: opt.title,
+      description: opt.description || '',
+      value: opt.value
+    }));
+    
+    // Add back option if not at root
+    if (currentNode !== 'root') {
+      choices.push({
+        title: chalk.gray('← Back'),
+        value: '__back__'
+      });
+    }
+    
+    choices.push({
+      title: chalk.gray('✕ Exit'),
+      value: '__exit__'
+    });
+    
+    const response = await prompts({
+      type: 'select',
+      name: 'choice',
+      message: node.question,
+      choices: choices
+    });
+    
+    if (!response.choice || response.choice === '__exit__') {
+      console.log(chalk.gray('\nGoodbye! 👋\n'));
+      process.exit(0);
+    }
+    
+    if (response.choice === '__back__') {
+      currentNode = history.pop() || 'root';
+      continue;
+    }
+    
+    // Find the selected option
+    const selected = node.options.find(opt => opt.value === response.choice);
+    
+    if (selected) {
+      // Show immediate result if available
+      if (selected.command) {
+        console.log(chalk.green('\n✨ Run this command:\n'));
+        console.log(chalk.bgBlack.white(`  $ ${selected.command}`));
+        
+        if (selected.available) {
+          console.log(chalk.yellow(`\n  ⚠️  Available in ${selected.available}`));
+        }
+        console.log();
+      }
+      
+      if (selected.steps) {
+        console.log(chalk.green('\n📝 Follow these steps:\n'));
+        selected.steps.forEach((step, i) => {
+          if (step.startsWith('//') || step.startsWith('#')) {
+            console.log(chalk.gray(step));
+          } else if (step === '') {
+            console.log();
+          } else if (step.includes('npm') || step.includes('npx')) {
+            console.log(chalk.bgBlack.white(`  $ ${step}`));
+          } else {
+            console.log(`  ${step}`);
+          }
+        });
+        console.log();
+      }
+      
+      if (selected.solution) {
+        console.log(chalk.green('\n💡 Solution:\n'));
+        console.log(chalk.white(selected.solution.explanation));
+        console.log(chalk.green('\nTry these commands:\n'));
+        selected.solution.commands.forEach(cmd => {
+          console.log(chalk.bgBlack.white(`  $ ${cmd}`));
+        });
+        console.log();
+      }
+      
+      if (selected.content) {
+        console.log(chalk.green('\n📚 Information:\n'));
+        console.log(selected.content);
+      }
+      
+      // Navigate to next level if exists
+      if (HELP_TREE[response.choice]) {
+        history.push(currentNode);
+        currentNode = response.choice;
+      } else {
+        // Ask to continue or exit
+        const cont = await prompts({
+          type: 'confirm',
+          name: 'continue',
+          message: 'Continue exploring help?',
+          initial: true
+        });
+        
+        if (!cont.continue) {
+          console.log(chalk.gray('\nGoodbye! 👋\n'));
+          process.exit(0);
+        }
+        
+        // Go back to previous menu
+        currentNode = history.pop() || 'root';
+      }
+    }
+  }
+}
+
+function showQuickHelp() {
+  console.log(chalk.yellow('\n🍠 SPAPS Quick Reference\n'));
+  
+  console.log(chalk.green('Common Commands:'));
+  console.log('  npx spaps local                  ' + chalk.gray('# Start local server'));
+  console.log('  npx spaps init                   ' + chalk.gray('# Initialize in project'));
+  console.log('  npx spaps create <name>          ' + chalk.gray('# Create new project (v0.3.0)'));
+  console.log('  npx spaps types                  ' + chalk.gray('# Generate types (v0.4.0)'));
+  console.log();
+  
+  console.log(chalk.green('Local Development:'));
+  console.log('  npx spaps local --port 3001      ' + chalk.gray('# Custom port'));
+  console.log('  npx spaps local --open           ' + chalk.gray('# Open browser'));
+  console.log('  npx spaps local --json           ' + chalk.gray('# JSON output'));
+  console.log();
+  
+  console.log(chalk.green('SDK Usage:'));
+  console.log('  npm install spaps-sdk            ' + chalk.gray('# Install SDK'));
+  console.log();
+  console.log(chalk.gray('  import { SPAPSClient } from "spaps-sdk"'));
+  console.log(chalk.gray('  const spaps = new SPAPSClient()'));
+  console.log(chalk.gray('  await spaps.login(email, password)'));
+  console.log();
+  
+  console.log(chalk.green('Debugging:'));
+  console.log('  curl http://localhost:3300/health   ' + chalk.gray('# Check server'));
+  console.log('  npx spaps help --interactive         ' + chalk.gray('# Interactive help'));
+  console.log();
+  
+  console.log(chalk.blue('📚 Docs: https://sweetpotato.dev'));
+  console.log(chalk.blue('💬 Discord: https://discord.gg/sweetpotato'));
+  console.log();
+}
+
+module.exports = {
+  showInteractiveHelp,
+  showQuickHelp,
+  HELP_TREE
+};