SaasBackend Documentation

📦 Installation

Install via NPM

npm install saasbackend

SaasBackend is a comprehensive micro SaaS template that includes authentication, billing, user management, and admin features out of the box.

⚙️ Environment Setup

Required Environment Variables

Create a .env file in your project root:

# Database
MONGODB_URI=mongodb://localhost:27017/your-db-name

# JWT Secrets (change in production!)
JWT_ACCESS_SECRET=your-access-secret-change-me
JWT_REFRESH_SECRET=your-refresh-secret-change-me

# Stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Admin Basic Auth
ADMIN_USERNAME=admin
ADMIN_PASSWORD=change-me-in-production

# CORS Configuration
CORS_ORIGIN=http://localhost:3000

# Public URL for Stripe redirects
PUBLIC_URL=http://localhost:3000
BILLING_RETURN_URL_RELATIVE=/dashboard

# Email (optional - for password reset)
RESEND_API_KEY=your-resend-api-key

🔧 Integration

Middleware Mode

Integrate with existing Express apps:

const express = require('express');
const saasbackend = require('saasbackend');

const app = express();
app.use('/api', saasbackend.middleware());

app.listen(3000);

Standalone Mode

Use as a complete backend:

const saasbackend = require('saasbackend');

const server = saasbackend.createServer({
  port: 3000,
  middleware: true
});

server.start();

🔐 Authentication

JWT-based Authentication

Secure authentication with access and refresh tokens:

User registration and login
Password reset functionality
Token refresh mechanism
Secure session management

Example: User Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

// Response
{
  "success": true,
  "data": {
    "user": { ... },
    "accessToken": "jwt-access-token",
    "refreshToken": "jwt-refresh-token"
  }
}

💳 Billing & Stripe Integration

Stripe Features

Subscription management
One-time payments
Billing portal integration
Webhook event handling
Invoice management

Create Checkout Session

POST /api/billing/create-checkout-session
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "priceId": "price_1234567890",
  "mode": "subscription"
}

// Response
{
  "success": true,
  "data": {
    "sessionId": "cs_test_...",
    "url": "https://checkout.stripe.com/pay/cs_test_..."
  }
}

👥 User Management

User Features

User profiles and settings
Activity logging
Waiting list management
User roles and permissions
Account deletion and data export

Get User Profile

GET /api/user/profile
Authorization: Bearer {access_token}

// Response
{
  "success": true,
  "data": {
    "id": "user_123",
    "email": "user@example.com",
    "name": "John Doe",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "subscription": {
      "status": "active",
      "plan": "pro"
    }
  }
}

📧 Email System

Email Features

Password reset emails
Welcome emails
Notification emails
Email logging and tracking
Resend integration
Email templates

Send Password Reset

POST /api/auth/forgot-password
Content-Type: application/json

{
  "email": "user@example.com"
}

// Response
{
  "success": true,
  "message": "Password reset email sent"
}

Email Configuration

Configure Resend API for email functionality:

# In your .env file
RESEND_API_KEY=re_123456789
FROM_EMAIL=noreply@yourapp.com
FROM_NAME=Your App Name

# Optional: Custom email templates
EMAIL_TEMPLATE_DIR=./templates/emails

⚙️ Admin Panel

Admin Features

User management and overview
Global settings configuration
System monitoring
Billing and subscription management
Activity logs and analytics

Access: /admin (Basic Auth required)

🌐 Global Settings

Configurable Settings

Site-wide configurations
Feature flags
Email templates
Billing settings
API rate limits

Get Global Settings

GET /api/global-settings
Authorization: Bearer {access_token}

// Response
{
  "success": true,
  "data": {
    "siteName": "Your SaaS App",
    "allowRegistration": true,
    "maintenanceMode": false,
    "emailNotifications": true
  }
}

🔗 API Endpoints

Authentication Endpoints

Method	Endpoint	Description
POST	/api/auth/register	User registration
POST	/api/auth/login	User login
POST	/api/auth/refresh	Refresh access token
GET	/api/auth/me	Get current user

Billing Endpoints

Method	Endpoint	Description
POST	/api/billing/create-checkout-session	Create Stripe checkout
POST	/api/billing/create-portal-session	Create billing portal
GET	/api/billing/subscription	Get subscription status

🔔 Webhooks

Stripe Webhooks

Automatic handling of Stripe events:

customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.payment_succeeded
invoice.payment_failed

POST /api/billing/webhook
Content-Type: application/json
Stripe-Signature: t=1234567890,v1=...

{
  "type": "customer.subscription.updated",
  "data": {
    "object": {
      "id": "sub_1234567890",
      "status": "active"
    }
  }
}

🧪 Testing

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Test Coverage

The project includes comprehensive test suites for:

Authentication flows
API endpoints
Billing operations
Email services
User management
Admin functions