spaps 0.4.3 → 0.5.1

package/README.md

@@ -1,11 +1,38 @@
 # 🍠 SPAPS CLI
 
-> **Sweet Potato Authentication & Payment Service CLI**  
-> Zero-config local development server with real Stripe integration
+> Sweet Potato Authentication & Payment Service CLI  
+> Zero‑config local development server with real Stripe integration
 
-[![npm version](https://badge.fury.io/js/spaps.svg)](https://badge.fury.io/js/spaps)
+## Hey, AI Agent — Read Me First 👋
+
+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:3300` 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.
+
+[![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)
 
+## SDK vs CLI
+
+- 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.
+
+Install the SDK in your app to call the API programmatically:
+
+```bash
+npm install spaps-sdk
+```
+
+Minimal init (works for both local and prod):
+
+```ts
+import { SweetPotatoSDK } from 'spaps-sdk'
+
+export const sdk = new SweetPotatoSDK({
+  apiUrl: process.env.SPAPS_API_URL || 'http://localhost:3300',
+  apiKey: process.env.SPAPS_API_KEY, // not required in local mode
+})
+```
+
 ## 🚀 Quick Start
 
 ```bash
@@ -17,7 +44,24 @@ npm install -g spaps
 spaps local
 ```
 
-**That's it!** Your local SPAPS server is now running at http://localhost:3456 🎉
+Your local SPAPS server runs at `http://localhost:3300` 🎉
+
+Point your app (via `SPAPS_API_URL`) to that URL and use `spaps-sdk` for calls.
+
+## Local → Prod
+
+- Local (dev):
+  - `SPAPS_API_URL=http://localhost:3300`
+  - `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
+
+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
 
 ## ✨ What is SPAPS?
 
@@ -39,12 +83,12 @@ Perfect for **rapid prototyping**, **hackathons**, and **local development**.
 Start a full-featured local server with zero configuration:
 
 ```bash
-spaps local                    # Default: http://localhost:3456
+spaps local                    # Default: http://localhost:3300
 spaps local --port 3000        # Custom port
 spaps local --json             # JSON output (CI-friendly)
 ```
 
-**Includes:**
+Includes:
 - ✅ Auto-authentication (no API keys needed)
 - ✅ Real Stripe test mode integration
 - ✅ Mock payment flows with webhooks
@@ -52,6 +96,12 @@ spaps local --json             # JSON output (CI-friendly)
 - ✅ API documentation at `/docs`
 - ✅ Test user switching via headers/query params
 
+Flags:
+
+- `--port <number>`: Set a custom port (default: 3456)
+- `--open`: Open docs in your browser after start
+- `--json`: JSON machine-readable output (ideal for CI)
+
 ### `spaps init` - Project Setup
 
 Initialize SPAPS in an existing project:
@@ -72,6 +122,20 @@ spaps status
 # Shows server status, Stripe connectivity, product sync status
 ```
 
+### 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
+
+### JSON Mode (CI)
+
+All commands that support `--json` will print machine-readable output. Example:
+
+```bash
+npx spaps local --port 0 --json | jq '.'
+```
+
 ## 🎯 Key Features
 
 ### 🔧 **Zero Configuration**
@@ -79,20 +143,20 @@ spaps status
 - Real Stripe test keys included
 - Automatic CORS for any frontend
 
-### 🎭 **Smart Test Users**
-Switch between user roles instantly:
+### 🎭 Smart Test Users (local‑only)
+Switch between user roles instantly (local server only):
 
 ```bash
-# Via query parameter
-curl "http://localhost:3456/api/auth/user?_user=admin"
+# Prefer header (local‑only)
+curl -H "X-Test-User: premium" "http://localhost:3300/api/auth/user"
 
-# Via header
-curl -H "X-Test-User: premium" "http://localhost:3456/api/auth/user"
+# Or query param (local‑only convenience)
+curl "http://localhost:3300/api/auth/user?_user=admin"
 ```
 
 Available roles: `user`, `admin`, `premium`
 
-### 💳 **Real Stripe Integration**
+### 💳 Real Stripe Integration
 - **Real API calls** to Stripe test mode
 - Create actual checkout sessions
 - Receive real webhooks
@@ -109,17 +173,22 @@ Visit `/admin` for a complete management interface:
 
 ## 🔌 API Endpoints
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/auth/login` | POST | Email/password authentication |
-| `/api/auth/wallet-sign-in` | POST | Wallet signature authentication |
-| `/api/auth/magic-link` | POST | Send magic link email |
-| `/api/stripe/products` | GET | List Stripe products |
-| `/api/stripe/checkout-sessions` | POST | Create checkout session |
-| `/api/stripe/webhooks` | POST | Handle Stripe webhooks |
-| `/api/admin/products` | GET/POST | Manage products |
-| `/health` | GET | Server health check |
-| `/docs` | GET | Interactive API documentation |
+| 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
 
@@ -128,7 +197,7 @@ Visit `/admin` for a complete management interface:
 ```javascript
 // React/Next.js example
 const createCheckout = async () => {
-  const response = await fetch('http://localhost:3456/api/stripe/checkout-sessions', {
+  const response = await fetch('http://localhost:3300/api/stripe/checkout-sessions', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
@@ -143,14 +212,14 @@ const createCheckout = async () => {
 };
 ```
 
-### Test Different User Roles
+### Test Different User Roles (local‑only)
 
 ```javascript
 // Test as admin user
-fetch('http://localhost:3456/api/auth/user?_user=admin')
+fetch('http://localhost:3300/api/auth/user?_user=admin')
 
 // Test wallet authentication  
-fetch('http://localhost:3456/api/auth/wallet-sign-in', {
+fetch('http://localhost:3300/api/auth/wallet-sign-in', {
   method: 'POST',
   body: JSON.stringify({
     wallet_address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa',
@@ -162,7 +231,7 @@ fetch('http://localhost:3456/api/auth/wallet-sign-in', {
 ## 🏗️ Development Workflow
 
 1. **Start SPAPS**: `npx spaps local`
-2. **Build your frontend** against `http://localhost:3456`
+2. **Build your frontend** against `http://localhost:3300`
 3. **Test payments** using Stripe's test cards
 4. **Monitor webhooks** at `/api/stripe/webhooks/test`
 5. **Manage data** via `/admin` dashboard
@@ -170,11 +239,43 @@ fetch('http://localhost:3456/api/auth/wallet-sign-in', {
 
 ## 🔒 Environment & Security
 
-**Local Mode Safety:**
-- Only runs on localhost (production-safe)
+Local mode safety:
+- Only runs on localhost
 - Uses Stripe test keys by default
 - All data stored locally in `.spaps/` directory
-- Headers indicate local development mode
+- Responses include local‑mode headers/metadata for visibility
+
+## Curl Examples (Header‑First)
+
+Authenticated (prod/staging):
+
+```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"
+  }'
+```
+
+Local (no key, role sim via header):
+
+```bash
+export SPAPS_API_URL=http://localhost:3300
+
+curl -X GET "$SPAPS_API_URL/api/auth/user" \
+  -H "X-Test-User: admin" \
+  -H "x-local-mode: true"
+```
+
+Note: `X-Test-User` and `x-local-mode` are ignored in production.
+
+ 
 
 **Stripe Configuration:**
 - Real Stripe test API integration
@@ -199,11 +300,112 @@ npm install --save-dev spaps
 
 - 📖 **Full Documentation**: [sweetpotato.dev](https://sweetpotato.dev)
 - 🔧 **Production Setup**: See deployment guides
-- 💬 **Get Help**: [GitHub Issues](https://github.com/yourusername/sweet-potato/issues)
+- 💬 **Get Help**: [GitHub Issues](https://github.com/buildooor/sweet-potato/issues)
 - 🚀 **Examples**: Check `/examples` directory
 
+## 🤝 Pair with the SDK
+
+Use the SDK in your app while running the local server:
+
+```bash
+npm install spaps-sdk
+```
+
+```ts
+import { SPAPSClient } from 'spaps-sdk';
+
+const spaps = new SPAPSClient(); // auto-detects local mode
+const { data } = await spaps.login('user@example.com', 'password');
+console.log('User:', data.user);
+```
+
+## 🚀 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:3300/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=sk_live_... # 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"}
+```
+
+---
+
+## 🔒 New in v0.5.0: Admin Middleware & Permissions!
+
+Built-in admin middleware and permission utilities for secure Express.js applications:
+
+```javascript
+const { requireAdmin, isAdminAccount } = require('spaps');
+
+// Protect admin routes
+app.get('/admin/dashboard', requireAdmin(), (req, res) => {
+  res.json({ message: 'Admin only!' });
+});
+
+// Check admin status
+if (isAdminAccount('buildooor@gmail.com')) {
+  // Grant admin access
+}
+```
+
+See [ADMIN_MIDDLEWARE.md](./ADMIN_MIDDLEWARE.md) for complete documentation.
+
 ---
 
-**Current Version**: v0.3.9  
+**Current Version**: v0.5.0  
 **License**: MIT  
-**Node.js**: >=16.0.0 required
+**Node.js**: >=16.0.0 required