saas-backend-kit 1.0.0

package/examples/express/.env.example

@@ -0,0 +1,41 @@
+NODE_ENV=development
+PORT=3000
+
+# JWT
+JWT_SECRET=your-super-secret-jwt-key-change-in-production-min-32-chars
+JWT_EXPIRES_IN=7d
+JWT_REFRESH_SECRET=your-super-secret-refresh-key-change-in-production
+JWT_REFRESH_EXPIRES_IN=30d
+
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# Database (optional)
+DATABASE_URL=postgresql://user:password@localhost:5432/mydb
+
+# Google OAuth (optional)
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+GOOGLE_REDIRECT_URI=http://localhost:3000/auth/google/callback
+
+# Email (SMTP) (optional)
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USER=your-smtp-user
+SMTP_PASS=your-smtp-password
+SMTP_FROM=noreply@yourdomain.com
+
+# Twilio SMS (optional)
+TWILIO_ACCOUNT_SID=
+TWILIO_AUTH_TOKEN=
+TWILIO_PHONE_NUMBER=
+
+# Slack (optional)
+SLACK_WEBHOOK_URL=
+
+# Rate Limiting
+RATE_LIMIT_WINDOW=1m
+RATE_LIMIT_LIMIT=100
+
+# Logger
+LOG_LEVEL=info

package/examples/express/app.ts

@@ -0,0 +1,203 @@
+import express from 'express';
+import { 
+  auth, 
+  rateLimit, 
+  logger, 
+  config, 
+  queue, 
+  notify, 
+  response,
+  createApp 
+} from '../src';
+
+config.load();
+
+const app = express();
+
+app.use(express.json());
+
+const authMiddleware = auth.initialize({
+  jwtSecret: process.env.JWT_SECRET || 'your-secret-key-change-in-production',
+  jwtExpiresIn: '7d',
+  refreshExpiresIn: '30d',
+  googleClientId: process.env.GOOGLE_CLIENT_ID,
+  googleClientSecret: process.env.GOOGLE_CLIENT_SECRET,
+  googleRedirectUri: process.env.GOOGLE_REDIRECT_URI,
+});
+
+app.use(authMiddleware);
+
+app.use(rateLimit({
+  window: '1m',
+  limit: 100,
+}));
+
+app.post('/auth/register', async (req, res) => {
+  try {
+    const { email, password, name } = req.body;
+    const result = await auth().register({ email, password, name });
+    res.success(result.tokens, 'Registration successful');
+  } catch (error: any) {
+    res.badRequest(error.message);
+  }
+});
+
+app.post('/auth/login', async (req, res) => {
+  try {
+    const { email, password } = req.body;
+    const result = await auth().login({ email, password });
+    res.success(result.tokens, 'Login successful');
+  } catch (error: any) {
+    res.unauthorized('Invalid credentials');
+  }
+});
+
+app.post('/auth/refresh', async (req, res) => {
+  try {
+    const { refreshToken } = req.body;
+    const tokens = await auth().refresh(refreshToken);
+    res.success(tokens);
+  } catch (error: any) {
+    res.unauthorized('Invalid refresh token');
+  }
+});
+
+app.get('/auth/google', async (req, res) => {
+  const url = await auth().getGoogleAuthUrl();
+  res.redirect(url);
+});
+
+app.get('/auth/google/callback', async (req, res) => {
+  try {
+    const { code } = req.query;
+    const result = await auth().handleGoogleCallback(code as string);
+    res.success(result.tokens, 'Google login successful');
+  } catch (error: any) {
+    res.badRequest('Google authentication failed');
+  }
+});
+
+app.get('/dashboard', auth.requireUser(), (req, res) => {
+  res.success({ message: 'Welcome to your dashboard', user: req.user });
+});
+
+app.get('/admin', auth.requireRole('admin'), (req, res) => {
+  res.success({ message: 'Admin area' });
+});
+
+app.get('/protected', auth.requirePermission('read'), (req, res) => {
+  res.success({ message: 'You have read permission' });
+});
+
+const emailQueue = queue.create('email', {
+  defaultJobOptions: {
+    attempts: 3,
+    backoff: {
+      type: 'exponential',
+      delay: 1000,
+    },
+  },
+});
+
+emailQueue.add('sendWelcomeEmail', { userId: '123', email: 'user@example.com' }, {
+  delay: 5000,
+});
+
+queue.process('email', async (job) => {
+  logger.info(`Processing email job`, { jobId: job.id, type: job.name });
+  
+  await notify.email({
+    to: job.data.email,
+    subject: 'Welcome!',
+    template: 'welcome',
+    templateData: { name: 'User', appName: 'My SaaS App' },
+  });
+  
+  return { sent: true };
+});
+
+app.post('/notify/email', async (req, res) => {
+  try {
+    const { to, subject, template, data } = req.body;
+    await notify.email({ to, subject, template, templateData: data });
+    res.success({ message: 'Email sent' });
+  } catch (error: any) {
+    res.internalError(error.message);
+  }
+});
+
+app.post('/notify/sms', async (req, res) => {
+  try {
+    const { to, message } = req.body;
+    await notify.sms({ to, message });
+    res.success({ message: 'SMS sent' });
+  } catch (error: any) {
+    res.internalError(error.message);
+  }
+});
+
+app.post('/notify/webhook', async (req, res) => {
+  try {
+    const { url, method, body, headers } = req.body;
+    const result = await notify.webhook({ url, method, body, headers });
+    res.success(result);
+  } catch (error: any) {
+    res.internalError(error.message);
+  }
+});
+
+app.post('/notify/slack', async (req, res) => {
+  try {
+    const { text, blocks } = req.body;
+    await notify.slack({ text, blocks });
+    res.success({ message: 'Slack notification sent' });
+  } catch (error: any) {
+    res.internalError(error.message);
+  }
+});
+
+app.get('/api/users', (req, res) => {
+  const users = [
+    { id: '1', name: 'John Doe', email: 'john@example.com' },
+    { id: '2', name: 'Jane Smith', email: 'jane@example.com' },
+  ];
+  
+  const page = parseInt(req.query.page as string) || 1;
+  const limit = parseInt(req.query.limit as string) || 10;
+  const total = users.length;
+  
+  res.paginated(users, page, limit, total);
+});
+
+app.get('/api/users/:id', (req, res) => {
+  const user = { id: req.params.id, name: 'John Doe', email: 'john@example.com' };
+  res.success(user);
+});
+
+app.post('/api/users', (req, res) => {
+  const user = { id: '3', ...req.body };
+  res.created(user, 'User created');
+});
+
+app.put('/api/users/:id', (req, res) => {
+  const user = { id: req.params.id, ...req.body };
+  res.updated(user, 'User updated');
+});
+
+app.delete('/api/users/:id', (req, res) => {
+  res.deleted('User deleted');
+});
+
+const PORT = config.int('PORT') || 3000;
+
+app.listen(PORT, () => {
+  logger.info(`Server running on port ${PORT}`);
+});
+
+process.on('SIGTERM', async () => {
+  logger.info('SIGTERM received, closing server');
+  await queue.closeAll();
+  process.exit(0);
+});
+
+export default app;

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "saas-backend-kit",
+  "version": "1.0.0",
+  "description": "Production-grade modular backend toolkit for building scalable SaaS applications",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.mjs",
+      "require": "./dist/auth/index.js"
+    },
+    "./queue": {
+      "types": "./dist/queue/index.d.ts",
+      "import": "./dist/queue/index.mjs",
+      "require": "./dist/queue/index.js"
+    },
+    "./notifications": {
+      "types": "./dist/notifications/index.d.ts",
+      "import": "./dist/notifications/index.mjs",
+      "require": "./dist/notifications/index.js"
+    },
+    "./logger": {
+      "types": "./dist/logger/index.d.ts",
+      "import": "./dist/logger/index.mjs",
+      "require": "./dist/logger/index.js"
+    },
+    "./rate-limit": {
+      "types": "./dist/rate-limit/index.d.ts",
+      "import": "./dist/rate-limit/index.mjs",
+      "require": "./dist/rate-limit/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.mjs",
+      "require": "./dist/config/index.js"
+    },
+    "./response": {
+      "types": "./dist/response/index.d.ts",
+      "import": "./dist/response/index.mjs",
+      "require": "./dist/response/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup && node copy-dts.js",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "saas",
+    "backend",
+    "express",
+    "fastify",
+    "auth",
+    "jwt",
+    "redis",
+    "queue",
+    "notifications",
+    "rate-limit"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "bcryptjs": "^2.4.3",
+    "bullmq": "^5.1.0",
+    "express": "^4.18.2",
+    "fastify": "^4.25.0",
+    "ioredis": "^5.3.2",
+    "jsonwebtoken": "^9.0.2",
+    "nodemailer": "^6.9.8",
+    "pino": "^8.17.2",
+    "pino-pretty": "^10.3.1",
+    "twilio": "^4.20.1",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/bcryptjs": "^2.4.6",
+    "@types/express": "^4.17.21",
+    "@types/jsonwebtoken": "^9.0.5",
+    "@types/node": "^20.10.6",
+    "@types/nodemailer": "^6.4.14",
+    "eslint": "^8.56.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.1.3"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0",
+    "fastify": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    }
+  }
+}

package/src/auth/express.ts

@@ -0,0 +1,250 @@
+import bcrypt from 'bcryptjs';
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+import { JWTPayload, LoginCredentials, RegisterData, User, AuthOptions } from './types';
+import { jwtService } from './jwt';
+import { rbacService } from './rbac';
+import { oauthService } from './oauth';
+
+export interface AuthUser extends JWTPayload {
+  id: string;
+  email: string;
+  role: string;
+}
+
+declare global {
+  namespace Express {
+    interface Request {
+      user?: AuthUser;
+    }
+  }
+}
+
+export interface UserStore {
+  findByEmail(email: string): Promise<User | null>;
+  findById(id: string): Promise<User | null>;
+  create(data: RegisterData): Promise<User>;
+  update(id: string, data: Partial<User>): Promise<User>;
+}
+
+class InMemoryUserStore implements UserStore {
+  private users: Map<string, User> = new Map();
+
+  async findByEmail(email: string): Promise<User | null> {
+    for (const user of this.users.values()) {
+      if (user.email === email) return user;
+    }
+    return null;
+  }
+
+  async findById(id: string): Promise<User | null> {
+    return this.users.get(id) || null;
+  }
+
+  async create(data: RegisterData): Promise<User> {
+    const id = Math.random().toString(36).substr(2, 9);
+    const hashedPassword = await bcrypt.hash(data.password, 10);
+    const user: User = {
+      id,
+      email: data.email,
+      password: hashedPassword,
+      role: data.role || 'user',
+      name: data.name,
+    };
+    this.users.set(id, user);
+    return user;
+  }
+
+  async update(id: string, data: Partial<User>): Promise<User> {
+    const user = this.users.get(id);
+    if (!user) throw new Error('User not found');
+    const updated = { ...user, ...data };
+    this.users.set(id, updated);
+    return updated;
+  }
+}
+
+export class AuthService {
+  private userStore: UserStore;
+  private options: Required<AuthOptions>;
+  private initialized: boolean = false;
+
+  constructor(options: AuthOptions = {}, userStore?: UserStore) {
+    this.options = {
+      jwtSecret: options.jwtSecret || process.env.JWT_SECRET || 'default-secret-change-in-production',
+      jwtExpiresIn: options.jwtExpiresIn || '7d',
+      refreshSecret: options.refreshSecret || process.env.JWT_REFRESH_SECRET || 'default-secret-change-in-production',
+      refreshExpiresIn: options.refreshExpiresIn || '30d',
+      googleClientId: options.googleClientId || process.env.GOOGLE_CLIENT_ID || '',
+      googleClientSecret: options.googleClientSecret || process.env.GOOGLE_CLIENT_SECRET || '',
+      googleRedirectUri: options.googleRedirectUri || process.env.GOOGLE_REDIRECT_URI || '',
+    };
+
+    this.userStore = userStore || new InMemoryUserStore();
+  }
+
+  async initialize(): Promise<void> {
+    if (this.options.googleClientId && this.options.googleClientSecret && this.options.googleRedirectUri) {
+      oauthService.registerProvider('google', {
+        name: 'google',
+        clientId: this.options.googleClientId,
+        clientSecret: this.options.googleClientSecret,
+        redirectUri: this.options.googleRedirectUri,
+        authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+        tokenUrl: 'https://oauth2.googleapis.com/token',
+        userInfoUrl: 'https://www.googleapis.com/oauth2/v2/userinfo',
+      });
+    }
+    this.initialized = true;
+  }
+
+  async register(data: RegisterData): Promise<{ user: User; tokens: { accessToken: string; refreshToken: string } }> {
+    const existing = await this.userStore.findByEmail(data.email);
+    if (existing) {
+      throw new Error('User already exists');
+    }
+
+    const user = await this.userStore.create(data);
+    const tokens = jwtService.generateTokenPair({
+      userId: user.id,
+      email: user.email,
+      role: user.role,
+    });
+
+    return { user, tokens };
+  }
+
+  async login(credentials: LoginCredentials): Promise<{ user: User; tokens: { accessToken: string; refreshToken: string } }> {
+    const user = await this.userStore.findByEmail(credentials.email);
+    if (!user || !user.password) {
+      throw new Error('Invalid credentials');
+    }
+
+    const isValid = await bcrypt.compare(credentials.password, user.password);
+    if (!isValid) {
+      throw new Error('Invalid credentials');
+    }
+
+    const tokens = jwtService.generateTokenPair({
+      userId: user.id,
+      email: user.email,
+      role: user.role,
+    });
+
+    return { user, tokens };
+  }
+
+  async refresh(refreshToken: string): Promise<{ accessToken: string; refreshToken: string }> {
+    return jwtService.refreshTokens(refreshToken);
+  }
+
+  async getGoogleAuthUrl(state?: string): Promise<string> {
+    return oauthService.getAuthorizationUrl('google', state);
+  }
+
+  async handleGoogleCallback(code: string): Promise<{ user: User; tokens: { accessToken: string; refreshToken: string } }> {
+    const { accessToken } = await oauthService.exchangeCode('google', code);
+    const userInfo = await oauthService.getUserInfo('google', accessToken);
+
+    let user = await this.userStore.findByEmail(userInfo.email);
+    
+    if (!user) {
+      user = await this.userStore.create({
+        email: userInfo.email,
+        password: Math.random().toString(36).substr(2, 20),
+        name: userInfo.name,
+        role: 'user',
+      });
+    }
+
+    const tokens = jwtService.generateTokenPair({
+      userId: user.id,
+      email: user.email,
+      role: user.role,
+    });
+
+    return { user, tokens };
+  }
+
+  getMiddleware(): RequestHandler {
+    return (req: Request, res: Response, next: NextFunction) => {
+      const authHeader = req.headers.authorization;
+      
+      if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        return res.status(401).json({ error: 'No token provided' });
+      }
+
+      const token = authHeader.substring(7);
+      
+      try {
+        const payload = jwtService.verifyToken(token);
+        req.user = {
+          ...payload,
+          id: payload.userId,
+        };
+        next();
+      } catch (error) {
+        return res.status(401).json({ error: 'Invalid token' });
+      }
+    };
+  }
+
+  requireUser(): RequestHandler {
+    return (req: Request, res: Response, next: NextFunction) => {
+      if (!req.user) {
+        return res.status(401).json({ error: 'Authentication required' });
+      }
+      next();
+    };
+  }
+
+  requireRole(role: string): RequestHandler {
+    return (req: Request, res: Response, next: NextFunction) => {
+      if (!req.user) {
+        return res.status(401).json({ error: 'Authentication required' });
+      }
+      if (!rbacService.hasRole(req.user.role, role)) {
+        return res.status(403).json({ error: 'Insufficient permissions' });
+      }
+      next();
+    };
+  }
+
+  requirePermission(permission: string): RequestHandler {
+    return (req: Request, res: Response, next: NextFunction) => {
+      if (!req.user) {
+        return res.status(401).json({ error: 'Authentication required' });
+      }
+      if (!rbacService.hasPermission(req.user.role, permission)) {
+        return res.status(403).json({ error: 'Insufficient permissions' });
+      }
+      next();
+    };
+  }
+}
+
+let authServiceInstance: AuthService | null = null;
+
+export function createAuth(options?: AuthOptions, userStore?: UserStore): AuthService {
+  authServiceInstance = new AuthService(options, userStore);
+  return authServiceInstance;
+}
+
+export function auth(): AuthService {
+  if (!authServiceInstance) {
+    authServiceInstance = new AuthService();
+  }
+  return authServiceInstance;
+}
+
+export const Auth = {
+  initialize: (options?: AuthOptions) => {
+    const service = createAuth(options);
+    return {
+      service,
+      getMiddleware: () => service.getMiddleware(),
+      requireUser: () => service.requireUser(),
+      requireRole: (role: string) => service.requireRole(role),
+      requirePermission: (permission: string) => service.requirePermission(permission),
+    };
+  },
+};

package/src/auth/fastify.ts

@@ -0,0 +1,65 @@
+import { FastifyInstance, FastifyRequest, FastifyReply, HookHandlerDoneFunction } from 'fastify';
+import { AuthService } from './express';
+import { JWTPayload } from './types';
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    user?: JWTPayload & { id: string };
+  }
+}
+
+export function registerAuthPlugin(fastify: FastifyInstance, options: { authService: AuthService }, done: HookHandlerDoneFunction) {
+  const { authService } = options;
+
+  fastify.decorate('authenticate', async (request: FastifyRequest, reply: FastifyReply) => {
+    const authHeader = request.headers.authorization;
+    
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return reply.status(401).send({ error: 'No token provided' });
+    }
+
+    const token = authHeader.substring(7);
+    
+    try {
+      const payload = authService['jwtService'].verifyToken(token);
+      request.user = {
+        ...payload,
+        id: payload.userId,
+      };
+    } catch (error) {
+      return reply.status(401).send({ error: 'Invalid token' });
+    }
+  });
+
+  fastify.decorate('requireUser', async (request: FastifyRequest, reply: FastifyReply) => {
+    if (!request.user) {
+      return reply.status(401).send({ error: 'Authentication required' });
+    }
+  });
+
+  fastify.decorate('requireRole', (role: string) => {
+    return async (request: FastifyRequest, reply: FastifyReply) => {
+      if (!request.user) {
+        return reply.status(401).send({ error: 'Authentication required' });
+      }
+      const { rbacService } = await import('./rbac');
+      if (!rbacService.hasRole(request.user.role, role)) {
+        return reply.status(403).send({ error: 'Insufficient permissions' });
+      }
+    };
+  });
+
+  fastify.decorate('requirePermission', (permission: string) => {
+    return async (request: FastifyRequest, reply: FastifyReply) => {
+      if (!request.user) {
+        return reply.status(401).send({ error: 'Authentication required' });
+      }
+      const { rbacService } = await import('./rbac');
+      if (!rbacService.hasPermission(request.user.role, permission)) {
+        return reply.status(403).send({ error: 'Insufficient permissions' });
+      }
+    };
+  });
+
+  done();
+}

package/src/auth/index.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './jwt';
+export * from './rbac';
+export * from './oauth';
+export * from './express';
+export * from './fastify';