spaps 0.7.1 → 0.7.2

package/README.md

@@ -1,438 +1,223 @@
-# 🍠 SPAPS CLI
+# spaps
 
-> Sweet Potato Authentication & Payment Service CLI  
-> Zero‑config local development server with real Stripe integration
+CLI and middleware package for local SPAPS workflows.
 
-## Hey, AI Agent — Read Me First 👋
+## TL;DR
 
-Are you an AI agent whose human just said “ship auth + payments fast” but can’t explain refresh tokens? Perfect. Fire up `spaps` and you’ll have auth, Stripe checkout, and docs live on `http://localhost:3301` before they can type “why isn’t this working I dont undrestand”. You focus on calling APIs; we handle users, tokens, CORS, and webhooks. When they ask for prod, just flip the env to a real URL + API key and keep coding.
+**The Problem**: Local auth and payment development is slow when every app has to bootstrap a backend, wire environment files, and remember the right health and docs commands.
 
-[![npm version](https://img.shields.io/npm/v/spaps.svg)](https://www.npmjs.com/package/spaps)
-![node](https://img.shields.io/badge/node-%3E%3D16-brightgreen)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+**The Solution**: `spaps` gives you a small CLI for local-server workflows plus exported admin middleware helpers for Node apps that integrate with SPAPS.
 
-## SDK vs CLI
+### Why Use `spaps`?
 
-- CLI (`spaps`): runs the local SPAPS server and tooling for development. No API key required, helpers enabled.
-- SDK (`spaps-sdk`): TypeScript client for your app code. Points at the same base URL and works in local and prod.
+| Feature | What It Does |
+| --- | --- |
+| Local server workflow | Start, stop, inspect, and diagnose a local SPAPS server from the CLI |
+| Project bootstrap | Create a starter `.env.local` for SPAPS-aware projects |
+| AI tooling output | Emit the local OpenAI-style tool spec with `spaps tools` |
+| Middleware exports | Reuse admin-permission helpers from the package API |
 
-Install the SDK in your app to call the API programmatically:
+## Installation
 
-```bash
-npm install spaps-sdk
-```
-
-Minimal init (works for both local and prod):
-
-```ts
-import { SPAPSClient } from 'spaps-sdk'
+### Run Without Installing
 
-export const sdk = new SPAPSClient({
-  apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3301',
-  apiKey: process.env.SPAPS_API_KEY, // not required in local mode
-})
+```bash
+npx spaps help
 ```
 
-## 🚀 Quick Start
+### Global Install
 
 ```bash
-# Run immediately with npx (recommended)
-npx spaps local
-
-# Or install globally
 npm install -g spaps
-spaps local
 ```
 
-Your local SPAPS server runs at `http://localhost:3301` 🎉
-
-- API docs (Swagger UI): `http://localhost:3301/docs`
-- OpenAPI JSON: `http://localhost:3301/openapi.json`
-
-Point your app (via `SPAPS_API_URL`) to that URL and use `spaps-sdk` for calls.
-
-## Local → Prod
+### Project Dependency
 
-- Local (dev):
-  - `SPAPS_API_URL=http://localhost:3301`
-  - `SPAPS_LOCAL_MODE=true` (or auto‑detected on localhost)
-  - API key optional; helpers available (test users, permissive CORS)
-- Prod:
-  - `SPAPS_API_URL=https://api.yourdomain`
-  - `SPAPS_API_KEY=spaps_…` required
-  - Local helpers disabled; CORS and rate limits enforced
+```bash
+npm install spaps
+```
 
-Headers policy:
-- Local: may send `x-local-mode: true`; role sim via `X-Test-User: admin` (local‑only)
-- Prod: must send `X-API-Key: $SPAPS_API_KEY`; do NOT use local‑only headers
+## Quick Example
 
-## ✨ What is SPAPS?
+```bash
+# Start the local server
+npx spaps local
 
-SPAPS provides a **complete authentication and payment backend** for your applications:
+# Check status
+npx spaps status
 
-- 🔐 **Multi-wallet auth** (Solana, Ethereum, Bitcoin, Base)
-- 📧 **Traditional auth** (email/password, magic links) 
-- 💳 **Real Stripe integration** (products, checkout, webhooks)
-- 🎭 **Test user switching** (`?_user=admin`)
-- 📊 **Admin dashboard** with analytics
-- 🌐 **CORS-ready** for any frontend
+# Initialize .env.local in the current project
+npx spaps init
 
-Perfect for **rapid prototyping**, **hackathons**, and **local development**.
+# Emit the local tool spec as JSON
+npx spaps tools --json
+```
 
-## 📋 Commands
+## CLI Commands
 
-### `spaps local` - Development Server
+### `spaps local [subcommand]`
 
-Start a full-featured local server with zero configuration:
+Start or stop the local SPAPS server.
 
 ```bash
-spaps local                         # Default: http://localhost:3301
-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)
+spaps local
+spaps local --port 3400
+spaps local --detach
+spaps local --open
+spaps local stop
 ```
 
-Includes:
-- ✅ Auto-authentication (no API keys needed)
-- ✅ Real Stripe test mode integration
-- ✅ Mock payment flows with webhooks
-- ✅ Admin dashboard at `/admin`
-- ✅ API documentation at `/docs`
-- ✅ Test user switching via headers/query params
-
-Flags:
+Supported flags:
 
-- `--port <number>`: Set a custom port (default: 3301)
-- `--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)
+- `--port <port>`
+- `--detach`
+- `--fresh`
+- `--from-backup <path>`
+- `--open`
+- `--json`
 
-### `spaps init` - Project Setup
-
-Initialize SPAPS in an existing project:
+### `spaps status`
 
 ```bash
-spaps init
-# ✅ Creates .env.local with Stripe test keys
-# ✅ Adds SPAPS client to your package.json
-# ✅ Generates basic integration examples
+spaps status
+spaps status --port 3400
+spaps status --json
 ```
 
-### `spaps status` - Health Check
-
-Check your local server and Stripe connection:
+### `spaps quickstart`
 
 ```bash
-spaps status
-# Shows server status, Stripe connectivity, product sync status
+spaps quickstart
+spaps quickstart --port 3400
+spaps quickstart --json
 ```
 
-### Other Commands
-
-- `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)
-
-All commands that support `--json` will print machine-readable output. Example:
+### `spaps init`
 
 ```bash
-npx spaps local --port 0 --json | jq '.'
+spaps init
+spaps init --json
 ```
 
-AI tool spec (OpenAI-style):
+### `spaps docs`
 
 ```bash
-npx spaps tools --json > spaps-tools.json
+spaps docs
+spaps docs --interactive
+spaps docs --search secure-messages
+spaps docs --json
 ```
 
-Run diagnostics:
+### `spaps tools`
 
 ```bash
-npx spaps doctor --json
+spaps tools
+spaps tools --port 3400
+spaps tools --format openai
+spaps tools --json
+```
 
-OpenAPI JSON:
+### `spaps doctor`
 
 ```bash
-curl http://localhost:3301/openapi.json | jq '.'
-```
+spaps doctor
+spaps doctor --port 3400
+spaps doctor --stripe mock
+spaps doctor --json
 ```
 
-## 🎯 Key Features
+### Placeholder Commands
 
-### 🔧 **Zero Configuration**
-- No setup required - works out of the box
-- Real Stripe test keys included
-- Automatic CORS for any frontend
+The CLI currently includes placeholders for:
 
-### 🎭 Smart Test Users (local‑only)
-Switch between user roles instantly (local server only):
+- `spaps create <name>`
+- `spaps types`
 
-```bash
-# Prefer header (local‑only)
-curl -H "X-Test-User: premium" "http://localhost:3301/api/auth/user"
+Treat them as reserved surfaces rather than stable workflows.
 
-# Or query param (local‑only convenience)
-curl "http://localhost:3301/api/auth/user?_user=admin"
-```
+## Middleware Example
 
-Available roles: `user`, `admin`, `premium`
-
-### 💳 Real Stripe Integration
-- **Real API calls** to Stripe test mode
-- Create actual checkout sessions
-- Receive real webhooks
-- Sync products to/from Stripe
-- Full webhook testing UI at `/api/stripe/webhooks/test`
-
-### 📊 **Admin Dashboard**
-Visit `/admin` for a complete management interface:
-- Revenue analytics
-- Product management
-- Order tracking
-- Data export/import
-- Real-time webhook monitoring
-
-## 🔌 API Endpoints
-
-| Endpoint | Method | SDK Mapping | Description |
-|----------|--------|-------------|-------------|
-| `/api/auth/login` | POST | `sdk.auth.signInWithPassword` | Email/password authentication |
-| `/api/auth/register` | POST | `sdk.auth.register` | Register new user |
-| `/api/auth/user` | GET | `sdk.auth.getCurrentUser` | Current authenticated user |
-| `/api/auth/wallet-sign-in` | POST | `sdk.auth.signInWithWallet` / `sdk.auth.authenticateWallet` | Wallet signature authentication |
-| `/api/auth/refresh` | POST | `sdk.auth.refreshToken` | Refresh access token |
-| `/api/auth/logout` | POST | `sdk.auth.logout` | Log out |
-| `/api/stripe/products` | GET | `sdk.payments.listProducts` | List Stripe products |
-| `/api/stripe/products/:id` | GET | `sdk.payments.getProduct` | Get product (+prices) |
-| `/api/stripe/prices` | POST | `sdk.payments.createPrice` | Create price (admin) |
-| `/api/stripe/checkout-sessions` | POST | `sdk.payments.createCheckoutSession` | Create checkout session |
-| `/api/stripe/checkout-sessions/:id` | GET | `sdk.payments.getCheckoutSession` | Retrieve checkout session |
-| `/api/stripe/webhooks` | POST | — | Stripe webhook receiver |
-| `/health` | GET | `sdk.healthCheck` | Server health check |
-| `/docs` | GET | — | Interactive API documentation |
-
-## 💡 Usage Examples
-
-### Frontend Integration
+The package exports admin middleware and helper utilities from its main module:
 
 ```javascript
-// React/Next.js example
-const createCheckout = async () => {
-  const response = await fetch('http://localhost:3301/api/stripe/checkout-sessions', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      price_id: 'price_1234567890',
-      success_url: 'http://localhost:3000/success',
-      cancel_url: 'http://localhost:3000/cancel'
-    })
-  });
-  
-  const { data } = await response.json();
-  window.location.href = data.url; // Redirect to Stripe Checkout
-};
-```
+const express = require('express');
+const { requireAdmin, requirePermission } = require('spaps');
 
-### Test Different User Roles (local‑only)
+const app = express();
 
-```javascript
-// Test as admin user
-fetch('http://localhost:3301/api/auth/user?_user=admin')
-
-// Test wallet authentication  
-fetch('http://localhost:3301/api/auth/wallet-sign-in', {
-  method: 'POST',
-  body: JSON.stringify({
-    wallet_address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
-    chain_type: 'bitcoin'
-  })
+app.get('/admin', requireAdmin(), (_req, res) => {
+  res.json({ ok: true });
 });
-```
 
-## 🏗️ Development Workflow
-
-1. **Start SPAPS**: `npx spaps local`
-2. **Build your frontend** against `http://localhost:3301`
-3. **Test payments** using Stripe's test cards
-4. **Monitor webhooks** at `/api/stripe/webhooks/test`
-5. **Manage data** via `/admin` dashboard
-6. **Export data** when ready for production
-
-## 🔒 Environment & Security
+app.post('/admin/products', requirePermission('manage_products'), (_req, res) => {
+  res.json({ created: true });
+});
+```
 
-Local mode safety:
-- Only runs on localhost
-- Uses Stripe test keys by default
-- All data stored locally in `.spaps/` directory
-- Responses include local‑mode headers/metadata for visibility
+## What `spaps init` Writes
 
-## Curl Examples (Header‑First)
+`spaps init` creates a `.env.local` with a local API URL starter and leaves existing files alone if they are already present.
 
-Authenticated (prod/staging):
+## Troubleshooting
 
-```bash
-export SPAPS_API_URL=https://api.yourdomain
-export SPAPS_API_KEY=spaps_XXXXXXXXXXXXXXXX
-
-curl -X POST "$SPAPS_API_URL/api/stripe/checkout-sessions" \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: $SPAPS_API_KEY" \
-  -d '{
-    "price_id": "price_1234567890",
-    "success_url": "https://yourapp/success",
-    "cancel_url": "https://yourapp/cancel"
-  }'
-```
+### Port already in use
 
-Local (no key, role sim via header):
+Start on a different port:
 
 ```bash
-export SPAPS_API_URL=http://localhost:3301
-
-curl -X GET "$SPAPS_API_URL/api/auth/user" \
-  -H "X-Test-User: admin" \
-  -H "x-local-mode: true"
+npx spaps local --port 3400
 ```
 
-Note: `X-Test-User` and `x-local-mode` are ignored in production.
+### Need machine-readable output
 
- 
+Use `--json` on supported commands such as `local`, `status`, `quickstart`, `init`, `docs`, `tools`, and `doctor`.
 
-**Stripe Configuration:**
-- Real Stripe test API integration
-- Webhook signature verification
-- Product/price synchronization
-- Customer portal simulation
+### Local server is not responding
 
-## 📦 Installation Options
+Check the current status first:
 
 ```bash
-# Use immediately (recommended)
-npx spaps local
+npx spaps status
+```
 
-# Install globally
-npm install -g spaps
+Then re-run the server with a clean start if needed:
 
-# Add to project dependencies
-npm install --save-dev spaps
+```bash
+npx spaps local --fresh
 ```
 
-## 🎓 Next Steps
+## Limitations
 
-- 📖 **Full Documentation**: [sweetpotato.dev](https://sweetpotato.dev)
-- 🔧 **Production Setup**: See deployment guides
-- 💬 **Get Help**: [GitHub Issues](https://github.com/buildooor/sweet-potato/issues)
-- 🚀 **Examples**: Check `/examples` directory
+- The README only documents commands and flags that are currently wired in the CLI dispatcher.
+- `create` and `types` are present as placeholders and should not be treated as finished product surfaces.
+- The package is primarily for local workflows, not full production deployment automation.
 
-## 🤝 Pair with the SDK
+## FAQ
 
-Use the SDK in your app while running the local server:
+### Does this package expose the TypeScript SDK?
 
-```bash
-npm install spaps-sdk
-```
+No. The SDK is the separate `spaps-sdk` package.
 
-```ts
-import { SPAPSClient } from 'spaps-sdk';
+### Can I use the CLI without installing globally?
 
-const spaps = new SPAPSClient(); // auto-detects local mode
-const { data } = await spaps.login('user@example.com', 'password');
-console.log('User:', data.user);
-```
+Yes. Use `npx spaps ...`.
 
-## 🚀 Production Deployment
-
-Ready to go live? SPAPS supports seamless migration from local to production:
-
-### Local → Production Workflow
-
-1. **Export Local Data**:
-   ```bash
-   # Export your products, orders, and customers
-   curl http://localhost:3301/api/admin/export > spaps-data.json
-   ```
-
-2. **Set Up Production Server**:
-   ```bash
-   # Deploy to your server (DigitalOcean, AWS, etc.)
-   # Example production server: http://104.131.188.214:3000
-   git clone https://github.com/build000r/sweet-potato
-   cd sweet-potato
-   npm install
-   ```
-
-3. **Configure Environment**:
-   ```bash
-   # Set production environment variables
-   SUPABASE_URL=https://your-project.supabase.co
-   SUPABASE_SERVICE_KEY=eyJhb...your-service-key
-   STRIPE_SECRET_KEY=<STRIPE_SECRET_KEY> # Your live Stripe key
-   JWT_SECRET=your-32-char-secure-secret
-   ```
-
-4. **Sync Products to Production Stripe**:
-   ```bash
-   # Import your local products to production Stripe
-   curl -X POST http://104.131.188.214:3000/api/v1/admin/products/sync \
-        -H "Content-Type: application/json" \
-        -d @spaps-data.json
-   ```
-
-5. **Update Frontend Config**:
-   ```javascript
-   // Change from local to production endpoint
-   const SPAPS_URL = 'http://104.131.188.214:3000'; // Your production server
-   ```
-
-### Production Features
-
-The production SPAPS server includes:
-- ✅ **Real Supabase integration** with RLS policies
-- ✅ **Live Stripe webhooks** with signature verification
-- ✅ **Multi-wallet authentication** (Solana, Ethereum, Base, Bitcoin)
-- ✅ **JWT authentication** with refresh tokens
-- ✅ **Rate limiting** and security middleware
-- ✅ **Usage tracking** and analytics
-- ✅ **Multi-tenant support** for multiple client apps
-
-### Health Check
-
-Check if your production server is running:
-```bash
-curl http://104.131.188.214:3000/health
-# Returns: {"status":"healthy","mode":"production"}
-```
+### Does `spaps init` overwrite my existing env file?
 
----
+No. It skips `.env.local` if the file already exists.
 
-## 🔒 New in v0.5.0: Admin Middleware & Permissions!
+### What does `spaps tools` output?
 
-Built-in admin middleware and permission utilities for secure Express.js applications:
+An OpenAI-style tool spec for the local SPAPS surface.
 
-```javascript
-const { requireAdmin, isAdminAccount } = require('spaps');
+### Is the admin middleware available as an import?
 
-// Protect admin routes
-app.get('/admin/dashboard', requireAdmin(), (req, res) => {
-  res.json({ message: 'Admin only!' });
-});
+Yes. The package exports the admin helpers from its main module and via the `./middleware` export path.
 
-// Check admin status
-if (isAdminAccount('buildooor@gmail.com')) {
-  // Grant admin access
-}
-```
+## About Contributions
 
-See [ADMIN_MIDDLEWARE.md](./ADMIN_MIDDLEWARE.md) for complete documentation.
+*About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
 
----
+## License
 
-**Current Version**: v0.5.0  
-**License**: MIT  
-**Node.js**: >=16.0.0 required
+UNLICENSED

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Sweet Potato Authentication & Payment Service CLI - Docker Compose orchestrator for local Python/FastAPI SPAPS server with built-in admin middleware",
   "main": "src/index.js",
   "bin": {