spaps 0.5.0 → 0.5.2

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

@@ -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 { SPAPSClient } from 'spaps-sdk'
+
+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
+})
+```
+
 ## 🚀 Quick Start
 
 ```bash
@@ -17,7 +44,27 @@ 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` 🎉
+
+- 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
+
+- 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 +86,14 @@ 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 --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:**
+Includes:
 - ✅ Auto-authentication (no API keys needed)
 - ✅ Real Stripe test mode integration
 - ✅ Mock payment flows with webhooks
@@ -52,6 +101,14 @@ 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: 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)
+
 ### `spaps init` - Project Setup
 
 Initialize SPAPS in an existing project:
@@ -72,6 +129,40 @@ 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
+- `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:
+
+```bash
+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**
@@ -79,20 +170,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 +200,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 +224,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 +239,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 +258,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 +266,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,9 +327,25 @@ npm install --save-dev spaps
 
 - 📖 **Full Documentation**: [sweetpotato.dev](https://sweetpotato.dev)
 - 🔧 **Production Setup**: See deployment guides
-- 💬 **Get Help**: [GitHub Issues](https://github.com/build000r/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:
@@ -211,7 +355,7 @@ Ready to go live? SPAPS supports seamless migration from local to production:
 1. **Export Local Data**:
    ```bash
    # Export your products, orders, and customers
-   curl http://localhost:3456/api/admin/export > spaps-data.json
+   curl http://localhost:3300/api/admin/export > spaps-data.json
    ```
 
 2. **Set Up Production Server**:
@@ -267,6 +411,28 @@ curl http://104.131.188.214:3000/health
 
 ---
 
-**Current Version**: v0.4.3  
+## 🔒 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.5.0  
 **License**: MIT  
-**Node.js**: >=16.0.0 required
+**Node.js**: >=16.0.0 required