spaps 0.5.1 → 0.5.3

package/AI_TOOLS.json

@@ -0,0 +1,114 @@
+{
+  "name": "spaps",
+  "version": "0.1.0",
+  "description": "Auth + payments via SPAPS (local by default). Start with: npx spaps local",
+  "base_url": "http://localhost:3300",
+  "auth": {
+    "local_mode": true,
+    "production": {
+      "header": "X-API-Key",
+      "env": "SPAPS_API_KEY"
+    }
+  },
+  "tools": [
+    {
+      "name": "login",
+      "description": "Login with email/password. Local mode accepts any values.",
+      "method": "POST",
+      "path": "/api/auth/login",
+      "parameters": {
+        "type": "object",
+        "required": ["email", "password"],
+        "properties": {
+          "email": { "type": "string" },
+          "password": { "type": "string" }
+        }
+      }
+    },
+    {
+      "name": "register",
+      "description": "Register a new user with email/password.",
+      "method": "POST",
+      "path": "/api/auth/register",
+      "parameters": {
+        "type": "object",
+        "required": ["email", "password"],
+        "properties": {
+          "email": { "type": "string" },
+          "password": { "type": "string" }
+        }
+      }
+    },
+    {
+      "name": "get_current_user",
+      "description": "Get the currently authenticated user.",
+      "method": "GET",
+      "path": "/api/auth/user",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "authorization": { "type": "string", "description": "Bearer <access_token>" }
+        }
+      }
+    },
+    {
+      "name": "create_checkout_session",
+      "description": "Create a Stripe Checkout session.",
+      "method": "POST",
+      "path": "/api/stripe/checkout-sessions",
+      "parameters": {
+        "type": "object",
+        "required": ["success_url", "cancel_url"],
+        "properties": {
+          "price_id": { "type": "string" },
+          "product_name": { "type": "string" },
+          "amount": { "type": "number" },
+          "currency": { "type": "string", "default": "usd" },
+          "success_url": { "type": "string" },
+          "cancel_url": { "type": "string" }
+        }
+      }
+    },
+    {
+      "name": "list_products",
+      "description": "List products (Stripe-backed or local).",
+      "method": "GET",
+      "path": "/api/stripe/products",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "active": { "type": "boolean" },
+          "limit": { "type": "number" }
+        }
+      }
+    },
+    {
+      "name": "request_magic_link",
+      "description": "Send a magic link for passwordless login (simulated locally).",
+      "method": "POST",
+      "path": "/api/auth/magic-link",
+      "parameters": {
+        "type": "object",
+        "required": ["email"],
+        "properties": {
+          "email": { "type": "string" }
+        }
+      }
+    },
+    {
+      "name": "get_wallet_nonce",
+      "description": "Get a nonce to sign for wallet authentication.",
+      "method": "POST",
+      "path": "/api/auth/nonce",
+      "parameters": {
+        "type": "object",
+        "required": ["wallet_address"],
+        "properties": {
+          "wallet_address": { "type": "string" },
+          "chain_type": { "type": "string", "enum": ["solana", "ethereum", "bitcoin", "base"] }
+        }
+      }
+    }
+  ]
+}
+

package/README.md

@@ -25,9 +25,9 @@ npm install spaps-sdk
 Minimal init (works for both local and prod):
 
 ```ts
-import { SweetPotatoSDK } from 'spaps-sdk'
+import { SPAPSClient } from 'spaps-sdk'
 
-export const sdk = new SweetPotatoSDK({
+export const sdk = new SPAPSClient({
   apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3300',
   apiKey: process.env.SPAPS_API_KEY, // not required in local mode
 })
@@ -46,6 +46,9 @@ spaps local
 
 Your local SPAPS server runs at `http://localhost:3300` 🎉
 
+- API docs (Swagger UI): `http://localhost:3300/docs`
+- OpenAPI JSON: `http://localhost:3300/openapi.json`
+
 Point your app (via `SPAPS_API_URL`) to that URL and use `spaps-sdk` for calls.
 
 ## Local → Prod
@@ -83,9 +86,11 @@ Perfect for **rapid prototyping**, **hackathons**, and **local development**.
 Start a full-featured local server with zero configuration:
 
 ```bash
-spaps local                    # Default: http://localhost:3300
-spaps local --port 3000        # Custom port
-spaps local --json             # JSON output (CI-friendly)
+spaps local                         # Default: http://localhost:3300
+spaps local --port 3000             # Custom port
+spaps local --stripe mock|real      # Choose Stripe mode (default: mock)
+spaps local --seed demo             # Seed demo products/customers/orders
+spaps local --json                  # JSON output (CI-friendly)
 ```
 
 Includes:
@@ -98,7 +103,9 @@ Includes:
 
 Flags:
 
-- `--port <number>`: Set a custom port (default: 3456)
+- `--port <number>`: Set a custom port (default: 3300)
+- `--stripe <mode>`: Stripe mode `mock` (offline, default) or `real` (test API)
+- `--seed <preset>`: Seed local data; supported: `demo`
 - `--open`: Open docs in your browser after start
 - `--json`: JSON machine-readable output (ideal for CI)
 
@@ -127,6 +134,8 @@ spaps status
 - `spaps help` — Quick help; `spaps help --interactive` for guided setup
 - `spaps docs` — SDK docs; `spaps docs --interactive` or `--search "query"`
 - `spaps quickstart` — Minimal SDK usage instructions
+- `spaps tools` — Output AI tool spec (use `--json` to save)
+- `spaps doctor` — Diagnose local environment and config
 
 ### JSON Mode (CI)
 
@@ -136,6 +145,24 @@ All commands that support `--json` will print machine-readable output. Example:
 npx spaps local --port 0 --json | jq '.'
 ```
 
+AI tool spec (OpenAI-style):
+
+```bash
+npx spaps tools --json > spaps-tools.json
+```
+
+Run diagnostics:
+
+```bash
+npx spaps doctor --json
+
+OpenAPI JSON:
+
+```bash
+curl http://localhost:3300/openapi.json | jq '.'
+```
+```
+
 ## 🎯 Key Features
 
 ### 🔧 **Zero Configuration**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Sweet Potato Authentication & Payment Service CLI - Zero-config local development with built-in admin middleware and permission utilities",
   "main": "src/index.js",
   "bin": {
@@ -29,21 +29,23 @@
     "ethereum"
   ],
   "author": "buildooor",
-  "license": "MIT",
+  "license": "UNLICENSED",
   "repository": {
     "type": "git",
-    "url": "https://github.com/buildooor/sweet-potato"
+    "url": "https://github.com/build000r"
   },
   "bugs": {
-    "url": "https://github.com/build000r/sweet-potato/issues"
+    "email": "buildooor@gmail.com"
   },
-  "homepage": "https://sweetpotato.dev",
+  "homepage": "https://www.buildooor.com/services",
   "dependencies": {
     "axios": "^1.6.0",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
     "cors": "^2.8.5",
     "express": "^4.18.2",
+    "js-yaml": "^4.1.0",
+    "swagger-ui-dist": "^5.17.14",
     "ora": "^5.4.1",
     "prompts": "^2.4.2",
     "stripe": "^18.5.0",
@@ -55,6 +57,7 @@
   "files": [
     "bin",
     "src",
+    "AI_TOOLS.json",
     "client.js",
     "README.md"
   ]

package/src/ai-tool-spec.js

@@ -0,0 +1,298 @@
+/**
+ * AI Tool Spec generator for SPAPS
+ * - Produces OpenAI-style function schemas for common SPAPS actions
+ * - Keeps defaults safe for local development (no API key required)
+ */
+
+const { DEFAULT_PORT } = require('./config');
+const fs = require('fs');
+const path = require('path');
+
+function tryLoadManifest() {
+  const candidates = [
+    path.resolve(process.cwd(), 'docs/manifest.json'),
+    path.resolve(__dirname, '../../../docs/manifest.json')
+  ];
+  for (const p of candidates) {
+    try {
+      if (fs.existsSync(p)) {
+        const raw = fs.readFileSync(p, 'utf8');
+        return JSON.parse(raw);
+      }
+    } catch {}
+  }
+  return null;
+}
+
+function tryLoadOpenAPI() {
+  const candidates = [
+    path.resolve(process.cwd(), 'docs/api-reference.yaml'),
+    path.resolve(__dirname, '../../../docs/api-reference.yaml')
+  ];
+  for (const p of candidates) {
+    try {
+      if (fs.existsSync(p)) {
+        const yaml = require('js-yaml');
+        const raw = fs.readFileSync(p, 'utf8');
+        return yaml.load(raw);
+      }
+    } catch {}
+  }
+  return null;
+}
+
+function buildOpenAIToolSpec({ port = DEFAULT_PORT } = {}) {
+  const baseUrl = `http://localhost:${port}`;
+  const spec = {
+    name: 'spaps',
+    version: '0.1.0',
+    description: 'Auth + payments via SPAPS (local by default). Start with: npx spaps local',
+    base_url: baseUrl,
+    auth: {
+      local_mode: true,
+      production: {
+        header: 'X-API-Key',
+        env: 'SPAPS_API_KEY'
+      }
+    },
+    tools: [
+      {
+        name: 'login',
+        description: 'Login with email/password. Local mode accepts any values.',
+        method: 'POST',
+        path: '/api/auth/login',
+        parameters: {
+          type: 'object',
+          required: ['email', 'password'],
+          properties: {
+            email: { type: 'string', description: 'Email address' },
+            password: { type: 'string', description: 'Plain text password' }
+          }
+        }
+      },
+      {
+        name: 'register',
+        description: 'Register a new user with email/password.',
+        method: 'POST',
+        path: '/api/auth/register',
+        parameters: {
+          type: 'object',
+          required: ['email', 'password'],
+          properties: {
+            email: { type: 'string' },
+            password: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'get_current_user',
+        description: 'Get the currently authenticated user. Uses bearer token from previous login.',
+        method: 'GET',
+        path: '/api/auth/user',
+        parameters: {
+          type: 'object',
+          properties: {
+            authorization: { type: 'string', description: 'Bearer <access_token>' }
+          }
+        }
+      },
+      {
+        name: 'create_checkout_session',
+        description: 'Create a Stripe Checkout session. In local mode uses Stripe test or mock based on USE_REAL_STRIPE.',
+        method: 'POST',
+        path: '/api/stripe/checkout-sessions',
+        parameters: {
+          type: 'object',
+          required: ['success_url', 'cancel_url'],
+          properties: {
+            price_id: { type: 'string', description: 'Existing Stripe price ID (preferred)' },
+            product_name: { type: 'string', description: 'Used when price_id not provided' },
+            amount: { type: 'number', description: 'Amount in cents if creating ad-hoc price' },
+            currency: { type: 'string', default: 'usd' },
+            success_url: { type: 'string' },
+            cancel_url: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'list_products',
+        description: 'List products (Stripe-backed or local).',
+        method: 'GET',
+        path: '/api/stripe/products',
+        parameters: {
+          type: 'object',
+          properties: {
+            active: { type: 'boolean' },
+            limit: { type: 'number' }
+          }
+        }
+      },
+      {
+        name: 'request_magic_link',
+        description: 'Send a magic link for passwordless login (local mode simulates delivery).',
+        method: 'POST',
+        path: '/api/auth/magic-link',
+        parameters: {
+          type: 'object',
+          required: ['email'],
+          properties: {
+            email: { type: 'string' }
+          }
+        }
+      },
+      {
+        name: 'get_wallet_nonce',
+        description: 'Get a nonce to sign for wallet authentication.',
+        method: 'POST',
+        path: '/api/auth/nonce',
+        parameters: {
+          type: 'object',
+          required: ['wallet_address'],
+          properties: {
+            wallet_address: { type: 'string' },
+            chain_type: { type: 'string', enum: ['solana', 'ethereum', 'bitcoin', 'base'] }
+          }
+        }
+      }
+    ]
+  };
+
+  // Default error shapes used for enrichment/merging
+  const defaultErrors = {
+    '400': {
+      type: 'object',
+      properties: {
+        success: { type: 'boolean' },
+        error: { type: 'object', properties: { code: { type: 'string' }, message: { type: 'string' } }, required: ['message'] }
+      },
+      required: ['error']
+    },
+    '401': {
+      type: 'object',
+      properties: { error: { type: 'string', enum: ['unauthorized'] }, message: { type: 'string' } },
+      required: ['error']
+    },
+    '403': {
+      type: 'object',
+      properties: { error: { type: 'string', enum: ['forbidden'] }, message: { type: 'string' } },
+      required: ['error']
+    },
+    '429': {
+      type: 'object',
+      properties: { error: { type: 'string', enum: ['rate_limited'] }, message: { type: 'string' } },
+      required: ['error']
+    },
+    '500': {
+      type: 'object',
+      properties: { error: { type: 'string', enum: ['server_error'] }, message: { type: 'string' } },
+      required: ['error']
+    }
+  };
+
+  // Attempt to align paths/methods with docs/manifest.json if available
+  try {
+    const manifest = tryLoadManifest();
+    if (manifest && Array.isArray(manifest.endpoints)) {
+      const find = (method, pathStr) => manifest.endpoints.find(e => e.method === method && e.path === pathStr);
+      const patchTool = (toolName, method, pathStr) => {
+        const t = spec.tools.find(x => x.name === toolName);
+        const ep = find(method, pathStr);
+        if (t && ep) {
+          t.method = ep.method;
+          t.path = ep.path;
+        }
+      };
+      patchTool('login', 'POST', '/api/auth/login');
+      patchTool('register', 'POST', '/api/auth/register');
+      patchTool('get_current_user', 'GET', '/api/auth/user');
+      patchTool('create_checkout_session', 'POST', '/api/stripe/checkout-sessions');
+      patchTool('list_products', 'GET', '/api/stripe/products');
+      patchTool('request_magic_link', 'POST', '/api/auth/magic-link');
+      patchTool('get_wallet_nonce', 'POST', '/api/auth/nonce');
+    }
+  } catch {
+    // Best-effort alignment only
+  }
+
+  // Attempt to enrich parameter schemas from OpenAPI
+  try {
+    const openapi = tryLoadOpenAPI();
+    if (openapi && openapi.paths) {
+      const findOp = (method, pathStr) => {
+        const ops = openapi.paths[pathStr];
+        if (!ops) return null;
+        return ops[String(method).toLowerCase()] || null;
+      };
+      const setBodySchema = (toolName, method, pathStr) => {
+        const t = spec.tools.find(x => x.name === toolName);
+        const op = findOp(method, pathStr);
+        const schema = op?.requestBody?.content?.['application/json']?.schema;
+        if (t && schema) {
+          t.parameters = schema;
+        }
+      };
+      const setResponses = (toolName, method, pathStr) => {
+        const t = spec.tools.find(x => x.name === toolName);
+        const op = findOp(method, pathStr);
+        if (t && op && op.responses) {
+          const responses = {};
+          const examples = {};
+          for (const [code, obj] of Object.entries(op.responses)) {
+            const schema = obj?.content?.['application/json']?.schema;
+            if (schema) responses[code] = schema;
+            const content = obj?.content?.['application/json'];
+            if (content?.example !== undefined) {
+              examples[code] = content.example;
+            } else if (content?.examples && typeof content.examples === 'object') {
+              const ex = {};
+              for (const [name, val] of Object.entries(content.examples)) {
+                if (val && typeof val === 'object') {
+                  if ('value' in val) ex[name] = val.value;
+                }
+              }
+              if (Object.keys(ex).length) examples[code] = ex;
+            }
+          }
+          if (Object.keys(responses).length) {
+            // Merge with default errors for completeness
+            const merged = { ...defaultErrors, ...responses };
+            t.responses = merged;
+          }
+          if (Object.keys(examples).length) t.examples = examples;
+        }
+      };
+      setBodySchema('login', 'POST', '/api/auth/login');
+      setBodySchema('register', 'POST', '/api/auth/register');
+      setBodySchema('create_checkout_session', 'POST', '/api/stripe/checkout-sessions');
+      setBodySchema('request_magic_link', 'POST', '/api/auth/magic-link');
+      setBodySchema('get_wallet_nonce', 'POST', '/api/auth/nonce');
+      setResponses('login', 'POST', '/api/auth/login');
+      setResponses('register', 'POST', '/api/auth/register');
+      setResponses('get_current_user', 'GET', '/api/auth/user');
+      setResponses('create_checkout_session', 'POST', '/api/stripe/checkout-sessions');
+      setResponses('list_products', 'GET', '/api/stripe/products');
+      setResponses('request_magic_link', 'POST', '/api/auth/magic-link');
+      setResponses('get_wallet_nonce', 'POST', '/api/auth/nonce');
+      // For GET endpoints with query/headers, leave minimal schema for simplicity
+    }
+  } catch {
+    // Ignore enrichment errors
+  }
+
+  // Add default error shapes if responses missing
+  spec.tools.forEach(t => {
+    if (!t.responses) t.responses = defaultErrors;
+  });
+
+  return spec;
+}
+
+function buildToolSpec({ format = 'openai', port = DEFAULT_PORT } = {}) {
+  switch (format) {
+    case 'openai':
+    default:
+      return buildOpenAIToolSpec({ port });
+  }
+}
+
+module.exports = { buildToolSpec };

package/src/cli-dispatcher.js

@@ -10,6 +10,10 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
 
   if (dryRun) {
     program.allowUnknownOption(true);
+    // Tolerate stray operands during unit tests (Commander normally errors)
+    if (typeof program.allowExcessArguments === 'function') {
+      program.allowExcessArguments(true);
+    }
   }
 
   program
@@ -44,16 +48,37 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     .command('local')
     .description('Start local SPAPS server (no API keys required!)')
     .option('-p, --port <port>', 'Port to run on', String(DEFAULT_PORT))
+    .option('-s, --stripe <mode>', 'Stripe mode: mock|real', 'mock')
+    .option('--seed <preset>', 'Seed local data: demo', 'none')
     .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,
-      }))
+      makeAction('local', (opts, cmd, isJson) => {
+        const out = {
+          port: Number(opts.port),
+          open: Boolean(opts.open),
+          json: isJson,
+        };
+        // Include optional flags only if explicitly provided by user
+        try {
+          const srcStripe = typeof cmd.getOptionValueSource === 'function' ? cmd.getOptionValueSource('stripe') : null;
+          const srcSeed = typeof cmd.getOptionValueSource === 'function' ? cmd.getOptionValueSource('seed') : null;
+          if (srcStripe === 'cli') out.stripe = String(opts.stripe || '').toLowerCase();
+          if (srcSeed === 'cli') out.seed = String(opts.seed || '').toLowerCase();
+        } catch (_) {
+          // Commander versions without getOptionValueSource; fall back to only including when present
+          if (typeof opts.stripe !== 'undefined') out.stripe = String(opts.stripe).toLowerCase();
+          if (typeof opts.seed !== 'undefined') out.seed = String(opts.seed).toLowerCase();
+        }
+        return out;
+      })
     );
-  if (dryRun) cmdLocal.allowUnknownOption(true);
+  if (dryRun) {
+    cmdLocal.allowUnknownOption(true);
+    if (typeof cmdLocal.allowExcessArguments === 'function') {
+      cmdLocal.allowExcessArguments(true);
+    }
+  }
 
   // spaps quickstart
   const cmdQuick = program
@@ -62,7 +87,12 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     .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);
+  if (dryRun) {
+    cmdQuick.allowUnknownOption(true);
+    if (typeof cmdQuick.allowExcessArguments === 'function') {
+      cmdQuick.allowExcessArguments(true);
+    }
+  }
 
   // spaps status
   const cmdStatus = program
@@ -71,7 +101,12 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     .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);
+  if (dryRun) {
+    cmdStatus.allowUnknownOption(true);
+    if (typeof cmdStatus.allowExcessArguments === 'function') {
+      cmdStatus.allowExcessArguments(true);
+    }
+  }
 
   // spaps init
   const cmdInit = program
@@ -79,21 +114,36 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     .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);
+  if (dryRun) {
+    cmdInit.allowUnknownOption(true);
+    if (typeof cmdInit.allowExcessArguments === 'function') {
+      cmdInit.allowExcessArguments(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);
+  if (dryRun) {
+    cmdCreate.allowUnknownOption(true);
+    if (typeof cmdCreate.allowExcessArguments === 'function') {
+      cmdCreate.allowExcessArguments(true);
+    }
+  }
 
   // spaps types
   const cmdTypes = program
     .command('types')
     .description('Generate TypeScript types (coming soon)')
     .action(makeAction('types', () => ({})));
-  if (dryRun) cmdTypes.allowUnknownOption(true);
+  if (dryRun) {
+    cmdTypes.allowUnknownOption(true);
+    if (typeof cmdTypes.allowExcessArguments === 'function') {
+      cmdTypes.allowExcessArguments(true);
+    }
+  }
 
   // spaps help
   const cmdHelp = program
@@ -104,7 +154,12 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     .action(
       makeAction('help', (opts) => ({ interactive: Boolean(opts.interactive), quick: Boolean(opts.quick) }))
     );
-  if (dryRun) cmdHelp.allowUnknownOption(true);
+  if (dryRun) {
+    cmdHelp.allowUnknownOption(true);
+    if (typeof cmdHelp.allowExcessArguments === 'function') {
+      cmdHelp.allowExcessArguments(true);
+    }
+  }
 
   // spaps docs
   const cmdDocs = program
@@ -116,7 +171,46 @@ function defineProgram({ handlers = {}, dryRun = false, version = '0.0.0', logo
     .action(
       makeAction('docs', (opts, _cmd, isJson) => ({ interactive: Boolean(opts.interactive), search: opts.search || null, json: isJson }))
     );
-  if (dryRun) cmdDocs.allowUnknownOption(true);
+  if (dryRun) {
+    cmdDocs.allowUnknownOption(true);
+    if (typeof cmdDocs.allowExcessArguments === 'function') {
+      cmdDocs.allowExcessArguments(true);
+    }
+  }
+
+  // spaps tools
+  const cmdTools = program
+    .command('tools')
+    .description('Output AI tool spec (OpenAI-style)')
+    .option('-p, --port <port>', 'Port to use for base_url', String(DEFAULT_PORT))
+    .option('-f, --format <format>', 'Spec format (openai)', 'openai')
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('tools', (opts, _cmd, isJson) => ({ port: Number(opts.port), format: String(opts.format || 'openai'), json: isJson }))
+    );
+  if (dryRun) {
+    cmdTools.allowUnknownOption(true);
+    if (typeof cmdTools.allowExcessArguments === 'function') {
+      cmdTools.allowExcessArguments(true);
+    }
+  }
+
+  // spaps doctor
+  const cmdDoctor = program
+    .command('doctor')
+    .description('Diagnose local environment and config')
+    .option('-p, --port <port>', 'Port to check', String(DEFAULT_PORT))
+    .option('-s, --stripe <mode>', 'Stripe mode: mock|real')
+    .option('--json', 'Output in JSON format')
+    .action(
+      makeAction('doctor', (opts, _cmd, isJson) => ({ port: Number(opts.port), stripe: opts.stripe || null, json: isJson }))
+    );
+  if (dryRun) {
+    cmdDoctor.allowUnknownOption(true);
+    if (typeof cmdDoctor.allowExcessArguments === 'function') {
+      cmdDoctor.allowExcessArguments(true);
+    }
+  }
 
   return { program, getIntents: () => intents };
 }

package/src/docs-html.js

@@ -3,7 +3,7 @@
  * Generates comprehensive documentation page
  */
 
-function generateDocsHTML(port = 3300) {
+function generateDocsHTML(port = 3300, notice) {
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -277,6 +277,7 @@ function generateDocsHTML(port = 3300) {
       <p class="subtitle">Sweet Potato Authentication & Payment Service</p>
       <span class="status-badge">✅ Local Mode Active - Port ${port}</span>
     </div>
+    ${notice ? `<div class="alert">${notice}</div>` : ''}
     
     <nav class="nav">
       <ul>
@@ -807,4 +808,4 @@ test().catch(console.error);</code></pre>
 </html>`;
 }
 
-module.exports = { generateDocsHTML };
+module.exports = { generateDocsHTML };

package/src/doctor.js

@@ -0,0 +1,217 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const net = require('net');
+const chalk = require('chalk');
+
+const { getServerStatus } = require('./ai-helper');
+const { DEFAULT_PORT } = require('./config');
+
+function checkNodeVersion() {
+  const version = process.versions.node || '0.0.0';
+  const major = parseInt(version.split('.')[0], 10) || 0;
+  const ok = major >= 16;
+  return {
+    check: 'node_version',
+    success: ok,
+    details: { version, requirement: '>=16' },
+    fix: ok ? null : 'Upgrade Node.js to v18+ (recommended)'
+  };
+}
+
+async function checkPort(port) {
+  // If server is running, we consider port check OK
+  const status = await getServerStatus(port);
+  if (status.running) {
+    return {
+      check: 'port',
+      success: true,
+      details: { port, running: true, url: status.url },
+      fix: null
+    };
+  }
+  // Otherwise ensure port is free to bind
+  const free = await new Promise((resolve) => {
+    const tester = net.createServer()
+      .once('error', () => resolve(false))
+      .once('listening', () => tester.once('close', () => resolve(true)).close())
+      .listen(port, '127.0.0.1');
+  });
+  return {
+    check: 'port',
+    success: free,
+    details: { port, running: false, free },
+    fix: free ? null : `Use a different port: npx spaps local --port ${port + 1}`
+  };
+}
+
+function checkEnvFile() {
+  const envPath = path.resolve(process.cwd(), '.env.local');
+  const exists = fs.existsSync(envPath);
+  let hasApiUrl = false;
+  if (exists) {
+    try {
+      const content = fs.readFileSync(envPath, 'utf8');
+      hasApiUrl = /SPAPS_API_URL\s*=/.test(content);
+    } catch {}
+  }
+  return {
+    check: 'env_file',
+    success: exists && hasApiUrl,
+    details: { path: envPath, exists, hasApiUrl },
+    fix: exists ? (hasApiUrl ? null : 'Add SPAPS_API_URL to .env.local (http://localhost:3300)') : 'Run: npx spaps init'
+  };
+}
+
+function checkWritePermissions() {
+  const dir = path.resolve(process.cwd(), '.spaps');
+  try {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const tmp = path.join(dir, '_doctor.tmp');
+    fs.writeFileSync(tmp, 'ok');
+    fs.unlinkSync(tmp);
+    return { check: 'write_permissions', success: true, details: { dir }, fix: null };
+  } catch (e) {
+    return { check: 'write_permissions', success: false, details: { dir, error: e.message }, fix: `Make directory writable: chmod -R u+rw ${dir}` };
+  }
+}
+
+function checkSDKInstalled() {
+  try {
+    require.resolve('spaps-sdk', { paths: [process.cwd()] });
+    return { check: 'sdk_installed', success: true, details: { package: 'spaps-sdk' }, fix: null };
+  } catch {
+    return { check: 'sdk_installed', success: false, details: { package: 'spaps-sdk' }, fix: 'npm install spaps-sdk' };
+  }
+}
+
+function checkStripeMode(stripeModeOpt) {
+  const mode = (stripeModeOpt || (process.env.USE_REAL_STRIPE === 'false' ? 'mock' : 'real')).toLowerCase();
+  const needsKey = mode === 'real';
+  const hasKey = Boolean(process.env.STRIPE_SECRET_KEY);
+  const ok = mode === 'mock' || (mode === 'real' && hasKey);
+  return {
+    check: 'stripe_mode',
+    success: ok,
+    details: { mode, needsKey, hasKey },
+    fix: ok ? null : (mode === 'real' ? 'Set STRIPE_SECRET_KEY or run with --stripe mock' : null)
+  };
+}
+
+function checkEnvTest() {
+  const envPath = path.resolve(process.cwd(), '.env.test');
+  if (!fs.existsSync(envPath)) {
+    return {
+      check: 'env_test',
+      success: false,
+      details: { path: envPath, exists: false },
+      fix: 'Create .env.test with SPAPS_API_URL=http://localhost:3300 (no real network keys)'
+    };
+  }
+  try {
+    const content = fs.readFileSync(envPath, 'utf8');
+    const hasLocalUrl = /SPAPS_API_URL\s*=\s*http:\/\/localhost:\d+/.test(content);
+    const hasApiKey = /SPAPS_API_KEY\s*=\s*\S+/.test(content);
+    const warns = [];
+    if (!hasLocalUrl) warns.push('SPAPS_API_URL should point to localhost');
+    if (hasApiKey) warns.push('SPAPS_API_KEY should not be set in tests');
+    return {
+      check: 'env_test',
+      success: hasLocalUrl && !hasApiKey,
+      details: { path: envPath, hasLocalUrl, hasApiKey },
+      fix: warns.length ? warns.join(' | ') : null
+    };
+  } catch (e) {
+    return { check: 'env_test', success: false, details: { error: e.message }, fix: 'Ensure .env.test is readable' };
+  }
+}
+
+async function checkNextJsPort() {
+  const defaultNextPort = 3000;
+  const inUse = await new Promise((resolve) => {
+    const tester = net.createServer()
+      .once('error', () => resolve(true))
+      .once('listening', () => tester.once('close', () => resolve(false)).close())
+      .listen(defaultNextPort, '127.0.0.1');
+  });
+  return {
+    check: 'next_port',
+    success: true,
+    details: { port: defaultNextPort, inUse, note: inUse ? 'Next.js likely running (good)' : 'Port free' },
+    fix: null
+  };
+}
+
+async function checkWebhook(port) {
+  const status = await getServerStatus(port);
+  if (!status.running) {
+    return {
+      check: 'webhook',
+      success: false,
+      details: { running: false },
+      fix: `Start server: npx spaps local --port ${port} --stripe mock`
+    };
+  }
+  try {
+    const http = require('http');
+    const payload = JSON.stringify({ id: 'evt_doctor_' + Date.now(), type: 'checkout.session.completed', data: { object: { id: 'cs_doctor_' + Date.now() } } });
+    const ok = await new Promise((resolve) => {
+      const req = http.request({ hostname: 'localhost', port, path: '/api/stripe/webhooks', method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) } }, (res) => {
+        resolve(res.statusCode >= 200 && res.statusCode < 300);
+      });
+      req.on('error', () => resolve(false));
+      req.write(payload);
+      req.end();
+    });
+    return { check: 'webhook', success: ok, details: { path: '/api/stripe/webhooks' }, fix: ok ? null : 'Use --stripe mock or ensure webhook handler is reachable' };
+  } catch (e) {
+    return { check: 'webhook', success: false, details: { error: e.message }, fix: 'Use --stripe mock or ensure server is running' };
+  }
+}
+
+function formatHuman(results) {
+  const ok = results.every(r => r.success);
+  console.log(chalk.yellow('\n🍠 SPAPS Doctor\n'));
+  results.forEach(r => {
+    const icon = r.success ? chalk.green('✔') : chalk.red('✖');
+    console.log(`${icon} ${r.check} ${chalk.gray(JSON.stringify(r.details))}`);
+    if (!r.success && r.fix) console.log(chalk.cyan(`   fix: ${r.fix}`));
+  });
+  console.log();
+  console.log(ok ? chalk.green('All checks passed!') : chalk.red('Some checks failed. See fixes above.'));
+}
+
+async function runDoctor({ port = DEFAULT_PORT, stripe = null, json = false } = {}) {
+  const results = [];
+  results.push(checkNodeVersion());
+  results.push(await checkPort(port));
+  // Warn if using 3000 which often collides with Next.js
+  if (port === 3000) {
+    results.push({
+      check: 'spaps_port_vs_next',
+      success: false,
+      details: { spaps_port: port, suggestion: 'Use 3300 for SPAPS to avoid Next.js conflicts' },
+      fix: 'Run: npx spaps local --port 3300'
+    });
+  } else {
+    results.push({ check: 'spaps_port_vs_next', success: true, details: { spaps_port: port }, fix: null });
+  }
+  results.push(checkEnvFile());
+  results.push(checkWritePermissions());
+  results.push(checkSDKInstalled());
+  results.push(checkStripeMode(stripe));
+  results.push(checkEnvTest());
+  results.push(await checkNextJsPort());
+  results.push(await checkWebhook(port));
+
+  const ok = results.every(r => r.success);
+  const payload = { success: ok, results, next_steps: ok ? [] : ['Apply suggested fixes and re-run: npx spaps doctor --json'] };
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    formatHuman(results);
+  }
+  return payload;
+}
+
+module.exports = { runDoctor };

package/src/handlers.js

@@ -5,6 +5,8 @@ const { handleError } = require('./error-handler');
 const { showInteractiveHelp, showQuickHelp } = require('./help-system');
 const { showInteractiveDocs, showQuickReference, searchDocs } = require('./docs-system');
 const { getQuickStartInstructions, getServerStatus, runQuickTest } = require('./ai-helper');
+const { buildToolSpec } = require('./ai-tool-spec');
+const { runDoctor } = require('./doctor');
 
 function createHandlers(version, logo) {
   return {
@@ -13,7 +15,7 @@ function createHandlers(version, logo) {
       if (!isJson) console.log(logo);
       try {
         const LocalServer = require('./local-server.js');
-        const server = new LocalServer({ port: options.port, json: isJson });
+        const server = new LocalServer({ port: options.port, json: isJson, stripeMode: options.stripe, seedMode: options.seed });
         if (isJson) {
           await server.start();
           console.log(JSON.stringify({
@@ -24,7 +26,7 @@ function createHandlers(version, logo) {
               docs: `http://localhost:${options.port}/docs`,
               mode: 'local-development',
               port: Number(options.port),
-              features: { autoAuth: true, corsEnabled: true, testUsers: ['user', 'admin', 'premium'], apiKeyRequired: false }
+              features: { autoAuth: true, corsEnabled: true, testUsers: ['user', 'admin', 'premium'], apiKeyRequired: false, stripeMode: options.stripe, seeded: options.seed }
             }
           }));
         } else {
@@ -147,9 +149,26 @@ function createHandlers(version, logo) {
       } else {
         showQuickReference();
       }
+    },
+    tools: async ({ options }) => {
+      const spec = buildToolSpec({ format: options.format || 'openai', port: options.port });
+      if (options.json) {
+        console.log(JSON.stringify(spec, null, 2));
+      } else {
+        console.log(chalk.yellow('\n🍠 SPAPS AI Tool Spec (OpenAI-style)\n'));
+        console.log('Base URL:', spec.base_url);
+        console.log('Tools:');
+        spec.tools.forEach((t, i) => {
+          console.log(chalk.green(`  ${i + 1}. ${t.name}`), '-', t.description);
+          console.log(chalk.gray(`     ${t.method} ${t.path}`));
+        });
+        console.log('\nTip: npx spaps tools --json > spaps-tools.json');
+      }
+    },
+    doctor: async ({ options }) => {
+      await runDoctor({ port: options.port || DEFAULT_PORT, stripe: options.stripe || null, json: options.json });
     }
   };
 }
 
 module.exports = { createHandlers };
-

package/src/local-server.js

@@ -8,19 +8,24 @@
 const express = require('express');
 const cors = require('cors');
 const chalk = require('chalk');
+const fs = require('fs');
+const path = require('path');
 const { generateDocsHTML } = require('./docs-html');
+let swaggerUiDist = null;
+try { swaggerUiDist = require('swagger-ui-dist'); } catch {}
 const StripeLocalManager = require('./stripe-local');
 const LocalAdminManager = require('./admin-local');
 
 // Stripe configuration for test mode
 const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY || 'sk_test_51S1WOy2HT0E1dOewiHvzt7T96PDwjocSDDUuc2ur569AVA5fDj4UpNM66lujrda1tTYrgooG0Z1dNFZfwEZuZdcA00nuVLJW67');
 const STRIPE_PUBLISHABLE_KEY = process.env.STRIPE_PUBLISHABLE_KEY || 'pk_test_51S1WOy2HT0E1dOewb2EkxZIaPkz7v3zMM9VxuBoxgNILYMmS85I4zrAWTkevyUQcaWlWUoC2NYnB8X5ZKd5e7Ifc005IzIW6H2';
-const USE_REAL_STRIPE = process.env.USE_REAL_STRIPE !== 'false'; // Default to true
 
 class LocalServer {
   constructor(options = {}) {
     this.port = options.port || process.env.PORT || 3456;
     this.json = options.json || false;
+    this.stripeMode = options.stripeMode || (process.env.USE_REAL_STRIPE === 'false' ? 'mock' : 'real');
+    this.seedMode = options.seedMode || 'none';
     this.app = express();
     this.stripeManager = null;
     this.adminManager = new LocalAdminManager();
@@ -29,6 +34,15 @@ class LocalServer {
     this.setupStripeRoutes();
     this.setupAdminRoutes();
     this.setupCatchAll();
+
+    // Optional demo seeding (idempotent)
+    if (this.seedMode === 'demo') {
+      try {
+        this.seedDemoData();
+      } catch (e) {
+        if (!this.json) console.warn(chalk.yellow(`⚠️  Seed failed: ${e.message}`));
+      }
+    }
   }
 
   setupMiddleware() {
@@ -44,6 +58,12 @@ class LocalServer {
     this.app.use(express.json());
     this.app.use(express.urlencoded({ extended: true }));
 
+    // Serve Swagger UI assets locally if available
+    if (swaggerUiDist && typeof swaggerUiDist.getAbsoluteFSPath === 'function') {
+      const uiPath = swaggerUiDist.getAbsoluteFSPath();
+      this.app.use('/swagger-ui', express.static(uiPath));
+    }
+
     // Local mode indicator
     this.app.use((req, res, next) => {
       res.setHeader('X-SPAPS-Mode', 'local-development');
@@ -67,6 +87,16 @@ class LocalServer {
   }
 
   setupRoutes() {
+    // OpenAPI JSON - try to serve repo spec; fallback to manifest; else minimal stub
+    this.app.get('/openapi.json', async (_req, res) => {
+      try {
+        const spec = await this.loadOpenApiSpec();
+        return res.json(spec);
+      } catch (e) {
+        return res.status(500).json({ error: 'Failed to generate OpenAPI', message: e.message });
+      }
+    });
+
     // Health check
     this.app.get('/health', (req, res) => {
       res.json({ 
@@ -167,7 +197,7 @@ class LocalServer {
     // Stripe checkout sessions endpoint - REAL or MOCK based on config
     this.app.post('/api/stripe/checkout-sessions', async (req, res) => {
       try {
-        if (USE_REAL_STRIPE) {
+        if (this.stripeMode === 'real') {
           // Real Stripe checkout session
           const { product_name, amount, currency = 'usd', success_url, cancel_url, price_id } = req.body;
           
@@ -254,7 +284,7 @@ class LocalServer {
     // Stripe products endpoint - REAL or MOCK based on config
     this.app.get('/api/stripe/products', async (req, res) => {
       try {
-        if (USE_REAL_STRIPE) {
+        if (this.stripeMode === 'real') {
           // Fetch real Stripe products
           const products = await stripe.products.list({
             active: req.query.active !== undefined ? req.query.active === 'true' : undefined,
@@ -418,7 +448,7 @@ class LocalServer {
     // Admin product sync endpoint - REAL or MOCK based on config
     this.app.post('/api/v1/admin/products/sync', async (req, res) => {
       try {
-        if (USE_REAL_STRIPE) {
+        if (this.stripeMode === 'real') {
           // Get local products from admin manager
           const localProducts = this.adminManager.listProducts();
           const syncResults = [];
@@ -532,19 +562,148 @@ class LocalServer {
       });
     });
 
-    // Documentation endpoint
+    // Documentation endpoint: prefer Swagger UI bound to /openapi.json
     this.app.get('/docs', (req, res) => {
-      res.send(generateDocsHTML(this.port));
+      if (swaggerUiDist && typeof swaggerUiDist.getAbsoluteFSPath === 'function') {
+        res.type('html').send(`
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>SPAPS API Docs</title>
+  <link rel="stylesheet" href="/swagger-ui/swagger-ui.css" />
+  <style>body { margin: 0; } #swagger-ui { max-width: 100%; }</style>
+ </head>
+ <body>
+  <div id="swagger-ui"></div>
+  <script src="/swagger-ui/swagger-ui-bundle.js"></script>
+  <script src="/swagger-ui/swagger-ui-standalone-preset.js"></script>
+  <script>
+    window.onload = () => {
+      window.ui = SwaggerUIBundle({
+        url: '/openapi.json',
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+        layout: 'BaseLayout'
+      });
+    };
+  </script>
+ </body>
+ </html>`);
+      } else {
+        // Fallback to the existing docs page if Swagger UI is not available
+        const msg = 'Using fallback docs page. Install Swagger UI assets for the full API explorer: npm install swagger-ui-dist';
+        res.send(generateDocsHTML(this.port, msg));
+      }
     });
   }
 
+  async loadOpenApiSpec() {
+    // Try YAML OpenAPI
+    const yamlCandidates = [
+      path.resolve(process.cwd(), 'docs/api-reference.yaml'),
+      path.resolve(__dirname, '../../../docs/api-reference.yaml')
+    ];
+    for (const p of yamlCandidates) {
+      try {
+        if (fs.existsSync(p)) {
+          let yaml;
+          try {
+            yaml = require('js-yaml');
+          } catch {}
+          if (yaml) {
+            const content = fs.readFileSync(p, 'utf8');
+            const parsed = yaml.load(content);
+            // ensure servers list points to local
+            parsed.servers = [{ url: `http://localhost:${this.port}` }];
+            return parsed;
+          }
+        }
+      } catch {}
+    }
+
+    // Fallback: build from manifest
+    const manifestCandidates = [
+      path.resolve(process.cwd(), 'docs/manifest.json'),
+      path.resolve(__dirname, '../../../docs/manifest.json')
+    ];
+    for (const p of manifestCandidates) {
+      try {
+        if (fs.existsSync(p)) {
+          const manifest = JSON.parse(fs.readFileSync(p, 'utf8'));
+          return this.buildOpenApiFromManifest(manifest);
+        }
+      } catch {}
+    }
+
+    // Last resort: minimal stub
+    return {
+      openapi: '3.0.0',
+      info: { title: 'SPAPS Local API', version: '0.0.0' },
+      servers: [{ url: `http://localhost:${this.port}` }],
+      paths: {
+        '/health': { get: { summary: 'Health', responses: { '200': { description: 'OK' } } } }
+      }
+    };
+  }
+
+  buildOpenApiFromManifest(manifest) {
+    const spec = {
+      openapi: '3.0.0',
+      info: { title: 'SPAPS API', version: String(manifest.version || '1.0.0') },
+      servers: [{ url: `http://localhost:${this.port}` }],
+      paths: {}
+    };
+    const toPath = (p) => p.replace(/:(\w+)/g, '{$1}');
+    for (const ep of manifest.endpoints || []) {
+      const pathKey = toPath(ep.path);
+      if (!spec.paths[pathKey]) spec.paths[pathKey] = {};
+      spec.paths[pathKey][String(ep.method || 'GET').toLowerCase()] = {
+        summary: ep.description || `${ep.method} ${ep.path}`,
+        tags: ep.tags || [],
+        responses: { '200': { description: 'OK' } }
+      };
+    }
+    return spec;
+  }
+
+  seedDemoData() {
+    // Add a couple of customers and a completed + pending order if none exist
+    const existingCustomers = this.adminManager.listCustomers();
+    const products = this.adminManager.listProducts();
+    if (existingCustomers.length === 0 && products.length > 0) {
+      const alice = this.adminManager.createCustomer({ email: 'alice@example.com', name: 'Alice' });
+      const bob = this.adminManager.createCustomer({ email: 'bob@example.com', name: 'Bob' });
+      const p = products[0];
+      const order1 = this.adminManager.createOrder({
+        customer_id: alice.id,
+        customer_email: alice.email,
+        product_id: p.id,
+        price_id: p.price_id,
+        amount: p.price,
+        currency: p.currency
+      });
+      this.adminManager.updateOrderStatus(order1.id, 'completed');
+      this.adminManager.createOrder({
+        customer_id: bob.id,
+        customer_email: bob.email,
+        product_id: p.id,
+        price_id: p.price_id,
+        amount: p.price,
+        currency: p.currency
+      });
+      if (!this.json) console.log(chalk.gray('🌱 Seeded demo customers and orders'));
+    }
+  }
+
   setupStripeRoutes() {
     // Enhanced Stripe Product Management - Full CRUD
     
     // GET /api/stripe/products - List all products with filtering
     this.app.get('/api/stripe/products', async (req, res) => {
       try {
-        if (USE_REAL_STRIPE) {
+        if (this.stripeMode === 'real') {
           const { active, category, limit = '100' } = req.query;
           
           const products = await stripe.products.list({
@@ -620,7 +779,7 @@ class LocalServer {
           });
         }
 
-        if (USE_REAL_STRIPE) {
+        if (this.stripeMode === 'real') {
           // Create product in Stripe
           const stripeProduct = await stripe.products.create({
             name,
@@ -718,7 +877,7 @@ class LocalServer {
         const { productId } = req.params;
         const { name, description, images, metadata, active } = req.body;
 
-        if (USE_REAL_STRIPE) {
+        if (this.stripeMode === 'real') {
           // Update in Stripe
           const updateData = {};
           if (name !== undefined) updateData.name = name;
@@ -780,7 +939,7 @@ class LocalServer {
           });
         }
 
-        if (USE_REAL_STRIPE) {
+        if (this.stripeMode === 'real') {
           const priceData = {
             product: product_id,
             unit_amount: parseInt(unit_amount),
@@ -852,7 +1011,7 @@ class LocalServer {
           });
         }
 
-        if (USE_REAL_STRIPE) {
+        if (this.stripeMode === 'real') {
           const stripeProduct = await stripe.products.update(productId, {
             default_price: price_id
           });
@@ -895,7 +1054,7 @@ class LocalServer {
       try {
         const { productId } = req.params;
 
-        if (USE_REAL_STRIPE) {
+        if (this.stripeMode === 'real') {
           // Archive in Stripe (can't truly delete)
           const stripeProduct = await stripe.products.update(productId, {
             active: false
@@ -1058,7 +1217,7 @@ class LocalServer {
       try {
         let event;
 
-        if (USE_REAL_STRIPE) {
+        if (this.stripeMode === 'real') {
           // Real Stripe webhook verification
           const sig = req.headers['stripe-signature'];
           const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
@@ -1076,7 +1235,13 @@ class LocalServer {
           }
         } else {
           // Mock mode - accept all webhooks
-          event = typeof req.body === 'string' ? JSON.parse(req.body) : req.body;
+          if (Buffer.isBuffer(req.body)) {
+            event = JSON.parse(req.body.toString());
+          } else if (typeof req.body === 'string') {
+            event = JSON.parse(req.body);
+          } else {
+            event = req.body;
+          }
         }
 
         if (!this.json) {
@@ -1494,7 +1659,7 @@ class LocalServer {
             console.log(chalk.yellow('🍠 SPAPS Local Development Server'));
             console.log(chalk.green(`✨ Running at: http://localhost:${this.port}`));
             console.log(chalk.blue(`📝 Documentation: http://localhost:${this.port}/docs`));
-            if (USE_REAL_STRIPE) {
+            if (this.stripeMode === 'real') {
               console.log(chalk.magenta('💳 Stripe: Real test mode (live API calls)'));
             } else {
               console.log(chalk.gray('💳 Stripe: Mock mode (simulated responses)'));
@@ -1535,4 +1700,4 @@ if (require.main === module) {
     console.log(chalk.yellow('\n👋 Shutting down...'));
     process.exit(0);
   });
-}
+}