# ⚡ Apex Framework - Quick Reference Card

## 🚀 Installation
```bash
pip install apex-saas-framework
```

---

## 📝 Minimal App (2 Lines!)
```python
from apex import Apex
app = Apex().app
```

---

## 🎯 Common Imports
```python
# Framework
from apex import Apex, ApexConfig, create_app

# Models
from apex import User, Organization, Role, Permission

# Decorators
from apex import auth_required, permission_required, role_required
```

---

## 🎨 Usage Patterns

### Pattern 1: Minimal
```python
from apex import Apex
app = Apex().app
```

### Pattern 2: With Models
```python
from apex import Apex, User, Organization
app = Apex(models=[User, Organization]).app
```

### Pattern 3: With Config
```python
from apex import Apex, ApexConfig
config = ApexConfig(title="My App")
app = Apex(config=config).app
```

### Pattern 4: Fluent API
```python
from apex import Apex
app = Apex().with_auth().with_payments().build()
```

### Pattern 5: Selective Features
```python
from apex import Apex
app = Apex(
    enable_auth=True,
    enable_payments=False
).app
```

---

## 🔧 Extend Models
```python
from apex import User
from sqlalchemy import Column, String

class MyUser(User):
    __tablename__ = "users"
    department = Column(String(100))
```

---

## 🔐 Add Protected Endpoint
```python
from apex import auth_required, User

@app.get("/api/profile")
@auth_required
async def profile(user: User):
    return {"email": user.email}
```

---

## ⚙️ Configuration (.env)
```bash
# Required
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/db

# Optional (has defaults)
SECRET_KEY=your-secret-key
APP_NAME=My SaaS App
ALLOWED_ORIGINS=http://localhost:3000

# PayPal (if using payments)
PAYPAL_CLIENT_ID=your-id
PAYPAL_CLIENT_SECRET=your-secret
PAYPAL_MODE=sandbox

# SendGrid (if using email)
SEND_GRID_API=your-api-key
FROM_EMAIL=noreply@yourdomain.com
```

---

## 🎯 Auto-Created Endpoints

### Authentication
- `POST /api/auth/signup` - Sign up
- `POST /api/auth/login` - Login
- `POST /api/auth/forgot-password` - Reset request
- `POST /api/auth/reset-password` - Reset password
- `POST /api/auth/change-password` - Change password

### Users
- `GET /api/users/me` - Current user
- `GET /api/users` - List users
- `GET /api/users/{id}` - Get user
- `PUT /api/users/{id}` - Update user

### Organizations
- `GET /api/organizations` - List
- `GET /api/organizations/{id}` - Get
- `POST /api/organizations` - Create
- `PUT /api/organizations/{id}` - Update

### Settings
- `GET /api/settings/user` - User settings
- `PUT /api/settings/user` - Update user settings
- `GET /api/settings/organization` - Org settings
- `PUT /api/settings/organization` - Update org settings

### Payments (PayPal)
- `POST /api/payments/create-subscription`
- `POST /api/payments/cancel`
- `GET /api/payments/subscriptions/{id}`

---

## 🧪 Test Your App

### Start Database (Docker)
```bash
docker run --name db -e POSTGRES_DB=myapp \
  -e POSTGRES_USER=admin -e POSTGRES_PASSWORD=password123 \
  -p 5432:5432 -d postgres:15
```

### Run App
```bash
uvicorn app:app --reload
```

### Visit Docs
http://localhost:8000/docs

---

## 📚 API Testing

### Signup
```bash
curl -X POST "http://localhost:8000/api/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "Pass123",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890",
    "country": "US",
    "organization_name": "My Company"
  }'
```

### Login
```bash
curl -X POST "http://localhost:8000/api/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@example.com&password=Pass123"
```

### Get Current User
```bash
curl -X GET "http://localhost:8000/api/users/me" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

## 🎨 Decorators

### @auth_required
```python
@app.get("/protected")
@auth_required
async def protected(user: User):
    return {"user": user.email}
```

### @permission_required
```python
@app.post("/admin")
@permission_required("admin:action")
async def admin():
    return {"message": "Admin only"}
```

### @role_required
```python
@app.get("/dashboard")
@role_required("Admin")
async def dashboard():
    return {"message": "Admin dashboard"}
```

---

## 🔧 Advanced Features

### ApexConfig Options
```python
ApexConfig(
    title="My App",
    enable_auth=True,
    enable_users=True,
    enable_organizations=True,
    enable_roles=True,
    enable_permissions=True,
    enable_modules=True,
    enable_settings=True,
    enable_payments=True,
    enable_cors=True,
    auto_create_tables=True
)
```

### Fluent API Methods
```python
.with_auth(enabled=True)
.with_users(enabled=True)
.with_organizations(enabled=True)
.with_roles(enabled=True)
.with_permissions(enabled=True)
.with_modules(enabled=True)
.with_settings(enabled=True)
.with_payments(enabled=True)
.with_cors(enabled=True)
.build()
```

---

## 📦 What You Get

✅ 40+ API endpoints  
✅ JWT authentication  
✅ User management  
✅ Organization management  
✅ RBAC (roles & permissions)  
✅ Settings management (JSONB)  
✅ Feature flags  
✅ PayPal integration  
✅ Email integration  
✅ Database auto-setup  
✅ API documentation  
✅ Multi-tenant support  

---

## 🆘 Troubleshooting

### Database connection failed
```bash
docker ps  # Check if running
docker restart db  # Restart if needed
```

### Module not found
```bash
pip install apex-saas-framework
```

### Port in use
```bash
uvicorn app:app --reload --port 8001
```

---

## 📚 Documentation

- **Simple Guide:** `SIMPLE_USAGE.md`
- **Full Guide:** `USER_GUIDE.md`
- **Examples:** `examples/` directory
- **What's New:** `WHATS_NEW.md`
- **API Docs:** http://localhost:8000/docs

---

## 🎯 Quick Start Checklist

- [ ] Install: `pip install apex-saas-framework`
- [ ] Create `.env` with `DATABASE_URL`
- [ ] Create `app.py` with `from apex import Apex; app = Apex().app`
- [ ] Run: `uvicorn app:app --reload`
- [ ] Visit: http://localhost:8000/docs
- [ ] Test signup endpoint
- [ ] Test login endpoint
- [ ] Build your features!

---

**That's everything you need to know!** 🚀

**From 0 to SaaS in 2 lines of code!**

