spaps 0.5.0 → 0.5.1

package/src/ai-helper.js

@@ -5,7 +5,9 @@
 
 const chalk = require('chalk');
 
-function getQuickStartInstructions(port = 3300) {
+const { DEFAULT_PORT } = require('./config');
+
+function getQuickStartInstructions(port = DEFAULT_PORT) {
   return {
     success: true,
     instructions: {
@@ -17,22 +19,20 @@ function getQuickStartInstructions(port = 3300) {
       step2: {
         description: "Create test file",
         filename: "test-spaps.js",
-        content: `const { SPAPSClient } = require('spaps-sdk');
+        content: `const { SweetPotatoSDK } = require('spaps-sdk');
 
 async function test() {
-  const spaps = new SPAPSClient({
-    apiUrl: 'http://localhost:${port}'
-  });
-  
-  // Test login
-  const { data } = await spaps.login('test@example.com', 'password');
-  console.log('✅ Login successful:', data.user.email);
-  
+  const sdk = new SweetPotatoSDK({ apiUrl: 'http://localhost:${port}' });
+
+  // Test email/password auth (local mode accepts any credentials)
+  const auth = await sdk.auth.signInWithPassword({ email: 'test@example.com', password: 'password' });
+  console.log('✅ Login successful:', auth.user.email);
+
   // Test authenticated request
-  const user = await spaps.getUser();
-  console.log('✅ Got user:', user.data.email);
-  
-  return { success: true, user: user.data };
+  const user = await sdk.auth.getCurrentUser();
+  console.log('✅ Got user:', user.email);
+
+  return { success: true, user };
 }
 
 test().then(console.log).catch(console.error);`
@@ -70,9 +70,9 @@ test().then(console.log).catch(console.error);`
       },
       {
         method: "POST",
-        path: "/api/stripe/create-checkout-session",
-        body: { price_id: "string", success_url: "string" },
-        response: { sessionId: "string", url: "string" }
+        path: "/api/stripe/checkout-sessions",
+        body: { price_id: "string", success_url: "string", cancel_url: "string" },
+        response: { id: "string", url: "string", status: "string" }
       },
       {
         method: "GET",
@@ -84,12 +84,12 @@ test().then(console.log).catch(console.error);`
     test_commands: {
       health_check: `curl http://localhost:${port}/health`,
       login: `curl -X POST http://localhost:${port}/api/auth/login -H "Content-Type: application/json" -d '{"email":"test@example.com","password":"password"}'`,
-      with_sdk: `node -e "const {SPAPSClient}=require('spaps-sdk');const s=new SPAPSClient();s.login('test@example.com','password').then(r=>console.log(JSON.stringify(r.data))).catch(console.error)"`
+      with_sdk: `node -e "const {SweetPotatoSDK}=require('spaps-sdk');const sdk=new SweetPotatoSDK({apiUrl:'http://localhost:${port}'});sdk.auth.signInWithPassword({email:'test@example.com',password:'password'}).then(r=>console.log(JSON.stringify(r.user))).catch(console.error)"`
     }
   };
 }
 
-function getServerStatus(port = 3300) {
+function getServerStatus(port = DEFAULT_PORT) {
   const http = require('http');
   
   return new Promise((resolve) => {
@@ -270,4 +270,4 @@ module.exports = {
   getQuickStartInstructions,
   getServerStatus,
   runQuickTest
-};
+};

package/src/cli-dispatcher.js

@@ -0,0 +1,139 @@
+// CLI dispatcher: builds a Commander program with pluggable handlers
+// Enables dry-run parsing for unit tests without executing side effects.
+
+const { Command } = require('commander');
+const { DEFAULT_PORT } = require('./config');
+
+function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo = null } = {}) {
+  const intents = [];
+  const program = new Command();
+
+  if (dryRun) {
+    program.allowUnknownOption(true);
+  }
+
+  program
+    .name('spaps')
+    .description('CLI for Sweet Potato Authentication & Payment Service')
+    .version(version)
+    .option('--json', 'Output in JSON format for machine parsing');
+
+  function makeAction(name, shape) {
+    return async function actionWrapper(...args) {
+      // Commander 11 passes (options, command) for subcommands without args
+      // For commands with args, it passes (arg1, arg2, ..., options, command)
+      const cmd = args[args.length - 1];
+      const options = args[args.length - 2] || {};
+      const parentJson = program.opts().json;
+      const isJson = Boolean(options.json || parentJson);
+
+      const intent = { name, options: { ...shape(options, cmd, isJson) } };
+      intents.push(intent);
+
+      if (dryRun) return intent;
+      const handler = handlers[name];
+      if (typeof handler === 'function') {
+        return await handler(intent, { program, cmd });
+      }
+      return intent;
+    };
+  }
+
+  // spaps local
+  const cmdLocal = program
+    .command('local')
+    .description('Start local SPAPS server (no API keys required!)')
+    .option('-p, --port <port>', 'Port to run on', String(DEFAULT_PORT))
+    .option('-o, --open', 'Open browser automatically', false)
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('local', (opts, _cmd, isJson) => ({
+        port: Number(opts.port),
+        open: Boolean(opts.open),
+        json: isJson,
+      }))
+    );
+  if (dryRun) cmdLocal.allowUnknownOption(true);
+
+  // spaps quickstart
+  const cmdQuick = program
+    .command('quickstart')
+    .description('Get quick start instructions (for AI agents)')
+    .option('-p, --port <port>', 'Port to check', String(DEFAULT_PORT))
+    .option('--json', 'Output in JSON format')
+    .action(makeAction('quickstart', (opts, _cmd, isJson) => ({ port: Number(opts.port), json: isJson })));
+  if (dryRun) cmdQuick.allowUnknownOption(true);
+
+  // spaps status
+  const cmdStatus = program
+    .command('status')
+    .description('Check if SPAPS server is running')
+    .option('-p, --port <port>', 'Port to check', String(DEFAULT_PORT))
+    .option('--json', 'Output in JSON format')
+    .action(makeAction('status', (opts, _cmd, isJson) => ({ port: Number(opts.port), json: isJson })));
+  if (dryRun) cmdStatus.allowUnknownOption(true);
+
+  // spaps init
+  const cmdInit = program
+    .command('init')
+    .description('Initialize SPAPS in current project')
+    .option('--json', 'Output in JSON format')
+    .action(makeAction('init', (_opts, _cmd, isJson) => ({ json: isJson })));
+  if (dryRun) cmdInit.allowUnknownOption(true);
+
+  // spaps create <name>
+  const cmdCreate = program
+    .command('create <name>')
+    .description('Create a new project with SPAPS (coming soon)')
+    .action(makeAction('create', (optsOrName, cmd) => ({ name: typeof optsOrName === 'string' ? optsOrName : cmd.args[0] })));
+  if (dryRun) cmdCreate.allowUnknownOption(true);
+
+  // spaps types
+  const cmdTypes = program
+    .command('types')
+    .description('Generate TypeScript types (coming soon)')
+    .action(makeAction('types', () => ({})));
+  if (dryRun) cmdTypes.allowUnknownOption(true);
+
+  // spaps help
+  const cmdHelp = program
+    .command('help')
+    .description('Show help and guides')
+    .option('-i, --interactive', 'Interactive help mode')
+    .option('-q, --quick', 'Quick reference')
+    .action(
+      makeAction('help', (opts) => ({ interactive: Boolean(opts.interactive), quick: Boolean(opts.quick) }))
+    );
+  if (dryRun) cmdHelp.allowUnknownOption(true);
+
+  // spaps docs
+  const cmdDocs = 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(
+      makeAction('docs', (opts, _cmd, isJson) => ({ interactive: Boolean(opts.interactive), search: opts.search || null, json: isJson }))
+    );
+  if (dryRun) cmdDocs.allowUnknownOption(true);
+
+  return { program, getIntents: () => intents };
+}
+
+function buildProgram(config = {}) {
+  return defineProgram(config).program;
+}
+
+function parseArgv(argv, config = {}) {
+  const { program, getIntents } = defineProgram({ ...config, dryRun: true });
+  program.exitOverride(() => { /* swallow exit in dry-run */ });
+  try {
+    program.parse(argv, { from: 'user' });
+  } catch (err) {
+    // Commander throws for help/version; we ignore in parse mode
+  }
+  return getIntents();
+}
+
+module.exports = { buildProgram, parseArgv };

package/src/config.js

@@ -0,0 +1,5 @@
+// Shared configuration for SPAPS CLI
+module.exports = {
+  DEFAULT_PORT: 3300
+};
+

package/src/docs-system.js

@@ -16,21 +16,21 @@ ${chalk.green('Installation:')}
   yarn add spaps-sdk
 
 ${chalk.green('Basic Usage:')}
-  ${chalk.gray('// ES6 Import')}
-  import { SPAPSClient } from 'spaps-sdk'
+  ${chalk.gray('// ES Module')}
+  import { SweetPotatoSDK } from 'spaps-sdk'
   
   ${chalk.gray('// CommonJS')}
-  const { SPAPSClient } = require('spaps-sdk')
+  const { SweetPotatoSDK } = 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
+  const sdk = new SweetPotatoSDK({
+    apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3300',
+    apiKey: process.env.SPAPS_API_KEY,  ${chalk.gray('// Not required in local mode')}
   })
+  
+  ${chalk.gray('// Sign in with email/password (local mode accepts any credentials)')}
+  const auth = await sdk.auth.signInWithPassword({ email: 'user@example.com', password: 'password' })
+  console.log('User:', auth.user)
 `
   },
 
@@ -39,48 +39,30 @@ ${chalk.green('Basic Usage:')}
     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)
+  const registered = await sdk.auth.register({ email, password })
+  console.log('User:', registered.user)
+  console.log('Token:', registered.access_token)
   
   ${chalk.gray('// Login existing user')}
-  const { data } = await spaps.login(email, password)
+  const auth = await sdk.auth.signInWithPassword({ email, password })
   
   ${chalk.gray('// Check authentication status')}
-  if (spaps.isAuthenticated()) {
-    const user = await spaps.getUser()
-    console.log('Current user:', user.data)
+  if (sdk.auth.isAuthenticated()) {
+    const user = await sdk.auth.getCurrentUser()
+    console.log('Current user:', user)
   }
   
   ${chalk.gray('// Logout')}
-  await spaps.logout()
+  await sdk.auth.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.gray('// One-call helper: authenticateWallet')}
+  const resp = await sdk.auth.authenticateWallet(walletAddress, signMessage, 'ethereum')
+  console.log('User:', resp.user)
 
 ${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()
+  ${chalk.gray('// Access token is managed internally; you can also set it manually')}
+  sdk.setAccessToken('jwt-token')
 `
   },
 
@@ -89,33 +71,25 @@ ${chalk.green('Token Management:')}
     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)')}
-  )
+  const session = await sdk.payments.createCheckoutSession({
+    price_id: 'price_123abc',
+    success_url: 'http://localhost:3000/success',
+    cancel_url: 'http://localhost:3000/cancel'
+  })
   
   ${chalk.gray('// Redirect to Stripe')}
-  window.location.href = session.data.url
+  window.location.href = session.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)
+  // Example subscription helpers would go here if enabled
   
   ${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)
+  // Usage APIs depend on your server config
 `
   },
 
@@ -132,18 +106,9 @@ ${chalk.green('Environment Variables:')}
   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
+  const sdk = new SweetPotatoSDK({
+    apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3300',
+    apiKey: process.env.SPAPS_API_KEY, ${chalk.gray('// Omit in local dev')}
   })
 
 ${chalk.green('Local Mode Detection:')}
@@ -153,7 +118,7 @@ ${chalk.green('Local Mode Detection:')}
   - No API URL is provided
   
   ${chalk.gray('// Check if in local mode')}
-  if (spaps.isLocalMode()) {
+  if (sdk.isLocalMode) {
     console.log('Running in local mode - no API key needed!')
   }
 `
@@ -165,14 +130,14 @@ ${chalk.green('Local Mode Detection:')}
 ${chalk.green('React Context Setup:')}
   ${chalk.gray('// contexts/SpapsContext.tsx')}
   import { createContext, useContext } from 'react'
-  import { SPAPSClient } from 'spaps-sdk'
+  import { SweetPotatoSDK } from 'spaps-sdk'
   
-  const spaps = new SPAPSClient()
-  const SpapsContext = createContext(spaps)
+  const sdk = new SweetPotatoSDK({ apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL || 'http://localhost:3300' })
+  const SpapsContext = createContext(sdk)
   
   export function SpapsProvider({ children }) {
     return (
-      <SpapsContext.Provider value={spaps}>
+      <SpapsContext.Provider value={sdk}>
         {children}
       </SpapsContext.Provider>
     )
@@ -273,26 +238,23 @@ ${chalk.green('Server Actions:')}
   ${chalk.gray('// app/actions/auth.ts')}
   'use server'
   
-  import { SPAPSClient } from 'spaps-sdk'
+  import { SweetPotatoSDK } from 'spaps-sdk'
   import { cookies } from 'next/headers'
   
-  const spaps = new SPAPSClient({
-    apiUrl: process.env.SPAPS_API_URL,
-    apiKey: process.env.SPAPS_API_KEY
-  })
+  const sdk = new SweetPotatoSDK({ 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)
+    const auth = await sdk.auth.signInWithPassword({ email, password })
     
     // Store token in cookie
-    cookies().set('spaps_token', data.access_token, {
+    cookies().set('spaps_token', auth.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 }
+    return { success: true, user: auth.user }
   }
 
 ${chalk.green('Middleware Protection:')}
@@ -322,17 +284,14 @@ ${chalk.green('Middleware Protection:')}
 ${chalk.green('Express Middleware:')}
   ${chalk.gray('// server.js')}
   const express = require('express')
-  const { SPAPSClient } = require('spaps-sdk')
+  const { SweetPotatoSDK } = require('spaps-sdk')
   
   const app = express()
-  const spaps = new SPAPSClient({
-    apiUrl: process.env.SPAPS_API_URL,
-    apiKey: process.env.SPAPS_API_KEY
-  })
+  const sdk = new SweetPotatoSDK({ 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
+    req.spaps = sdk
     next()
   })
   
@@ -346,8 +305,8 @@ ${chalk.green('Express Middleware:')}
     
     try {
       req.spaps.setAccessToken(token)
-      const { data } = await req.spaps.getUser()
-      req.user = data
+      const user = await req.spaps.auth.getCurrentUser()
+      req.user = user
       next()
     } catch (error) {
       res.status(401).json({ error: 'Invalid token' })
@@ -360,8 +319,8 @@ ${chalk.green('Route Examples:')}
     const { email, password } = req.body
     
     try {
-      const { data } = await req.spaps.login(email, password)
-      res.json(data)
+      const auth = await req.spaps.auth.signInWithPassword({ email, password })
+      res.json(auth)
     } catch (error) {
       res.status(401).json({ error: 'Invalid credentials' })
     }
@@ -567,17 +526,17 @@ ${chalk.green('E2E Testing with Cypress:')}
 ${chalk.green('Mocking for Tests:')}
   ${chalk.gray('// Mock SPAPS client')}
   jest.mock('spaps-sdk', () => ({
-    SPAPSClient: jest.fn().mockImplementation(() => ({
-      login: jest.fn().mockResolvedValue({
-        data: {
+    SweetPotatoSDK: jest.fn().mockImplementation(() => ({
+      auth: {
+        signInWithPassword: jest.fn().mockResolvedValue({
           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' }
-      })
+          access_token: 'mock-token',
+          refresh_token: 'mock-refresh'
+        }),
+        isAuthenticated: jest.fn().mockReturnValue(true),
+        getCurrentUser: jest.fn().mockResolvedValue({ id: '123', email: 'test@example.com' })
+      },
+      setAccessToken: jest.fn()
     }))
   }))
 `
@@ -587,39 +546,29 @@ ${chalk.green('Mocking for Tests:')}
     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}>
+  sdk.auth.signInWithPassword({ email, password }): Promise<AuthResponse>
+  sdk.auth.register({ email, password, username? }): Promise<AuthResponse>
+  sdk.auth.authenticateWallet(address, signFn, chain?): Promise<AuthResponse>
+  sdk.auth.refreshToken(refreshToken): Promise<AuthResponse>
+  sdk.auth.logout(): Promise<void>
+  sdk.auth.getCurrentUser(): Promise<User>
 
 ${chalk.green('Payment Methods:')}
-  createCheckoutSession(priceId: string, successUrl: string, cancelUrl?: string): Promise<{data: CheckoutSession}>
-  getSubscription(): Promise<{data: Subscription}>
-  cancelSubscription(): Promise<void>
+  sdk.payments.createCheckoutSession({ price_id, success_url, cancel_url }): Promise<CheckoutSession>
+  sdk.payments.getCheckoutSession(id): Promise<CheckoutSession>
+  sdk.payments.listProducts({ category?, active?, limit? }): Promise<ProductsListResponse>
 
 ${chalk.green('Usage Methods:')}
-  getUsageBalance(): Promise<{data: UsageBalance}>
-  recordUsage(feature: string, amount: number): Promise<void>
+  See server docs if enabled
 
 ${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')}
+  sdk.setAccessToken(token: string): void
+  sdk.clearAccessToken(): void
 
 ${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
+  ${chalk.gray('// Methods generally return typed objects directly')}
+  const auth = await sdk.auth.signInWithPassword({ email, password })
+  console.log(auth.access_token)
 `
   }
 };
@@ -636,7 +585,7 @@ ${chalk.green('Authentication Endpoints:')}
   GET    /api/auth/user             ${chalk.gray('Get current user')}
 
 ${chalk.green('Stripe Endpoints:')}
-  POST   /api/stripe/create-checkout-session  ${chalk.gray('Create Stripe checkout')}
+  POST   /api/stripe/checkout-sessions       ${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')}
@@ -803,4 +752,4 @@ module.exports = {
   searchDocs,
   SDK_DOCS,
   API_ENDPOINTS
-};
+};