saas-backend-kit 1.0.0

package/src/auth/jwt.ts

@@ -0,0 +1,47 @@
+import jwt from 'jsonwebtoken';
+import { JWTPayload, TokenPair } from './types';
+import { config } from '../config';
+
+export class JWTService {
+  private secret: string;
+  private expiresIn: string;
+  private refreshSecret: string;
+  private refreshExpiresIn: string;
+
+  constructor(options: { jwtSecret?: string; jwtExpiresIn?: string; refreshSecret?: string; refreshExpiresIn?: string } = {}) {
+    this.secret = options.jwtSecret || config.get('JWT_SECRET') || 'default-secret-change-in-production';
+    this.expiresIn = options.jwtExpiresIn || config.get('JWT_EXPIRES_IN') || '7d';
+    this.refreshSecret = options.refreshSecret || config.get('JWT_REFRESH_SECRET') || this.secret;
+    this.refreshExpiresIn = options.refreshExpiresIn || config.get('JWT_REFRESH_EXPIRES_IN') || '30d';
+  }
+
+  generateToken(payload: JWTPayload): string {
+    return jwt.sign(payload, this.secret, { expiresIn: this.expiresIn });
+  }
+
+  generateRefreshToken(payload: JWTPayload): string {
+    return jwt.sign(payload, this.refreshSecret, { expiresIn: this.refreshExpiresIn });
+  }
+
+  generateTokenPair(payload: JWTPayload): TokenPair {
+    return {
+      accessToken: this.generateToken(payload),
+      refreshToken: this.generateRefreshToken(payload),
+    };
+  }
+
+  verifyToken(token: string): JWTPayload {
+    return jwt.verify(token, this.secret) as JWTPayload;
+  }
+
+  verifyRefreshToken(token: string): JWTPayload {
+    return jwt.verify(token, this.refreshSecret) as JWTPayload;
+  }
+
+  refreshTokens(refreshToken: string): TokenPair {
+    const payload = this.verifyRefreshToken(refreshToken);
+    return this.generateTokenPair(payload);
+  }
+}
+
+export const jwtService = new JWTService();

package/src/auth/oauth.ts

@@ -0,0 +1,117 @@
+import { OAuthProvider } from './types';
+import { config } from '../config';
+
+export interface OAuthUserInfo {
+  id: string;
+  email: string;
+  name?: string;
+  picture?: string;
+}
+
+export class OAuthService {
+  private providers: Map<string, OAuthProvider> = new Map();
+
+  constructor() {
+    const googleClientId = config.get('GOOGLE_CLIENT_ID');
+    const googleClientSecret = config.get('GOOGLE_CLIENT_SECRET');
+    const googleRedirectUri = config.get('GOOGLE_REDIRECT_URI');
+
+    if (googleClientId && googleClientSecret && googleRedirectUri) {
+      this.registerProvider('google', {
+        name: 'google',
+        clientId: googleClientId,
+        clientSecret: googleClientSecret,
+        redirectUri: googleRedirectUri,
+        authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+        tokenUrl: 'https://oauth2.googleapis.com/token',
+        userInfoUrl: 'https://www.googleapis.com/oauth2/v2/userinfo',
+      });
+    }
+  }
+
+  registerProvider(name: string, provider: OAuthProvider): void {
+    this.providers.set(name, provider);
+  }
+
+  getProvider(name: string): OAuthProvider | undefined {
+    return this.providers.get(name);
+  }
+
+  getAuthorizationUrl(providerName: string, state?: string): string {
+    const provider = this.getProvider(providerName);
+    if (!provider) {
+      throw new Error(`OAuth provider ${providerName} not registered`);
+    }
+
+    const params = new URLSearchParams({
+      client_id: provider.clientId,
+      redirect_uri: provider.redirectUri,
+      response_type: 'code',
+      scope: 'openid email profile',
+      state: state || '',
+    });
+
+    return `${provider.authorizationUrl}?${params.toString()}`;
+  }
+
+  async exchangeCode(providerName: string, code: string): Promise<{ accessToken: string; refreshToken?: string }> {
+    const provider = this.getProvider(providerName);
+    if (!provider) {
+      throw new Error(`OAuth provider ${providerName} not registered`);
+    }
+
+    const response = await fetch(provider.tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({
+        client_id: provider.clientId,
+        client_secret: provider.clientSecret,
+        code,
+        grant_type: 'authorization_code',
+        redirect_uri: provider.redirectUri,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`OAuth token exchange failed: ${error}`);
+    }
+
+    const data = await response.json();
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+    };
+  }
+
+  async getUserInfo(providerName: string, accessToken: string): Promise<OAuthUserInfo> {
+    const provider = this.getProvider(providerName);
+    if (!provider) {
+      throw new Error(`OAuth provider ${providerName} not registered`);
+    }
+
+    const response = await fetch(provider.userInfoUrl, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`OAuth user info fetch failed: ${error}`);
+    }
+
+    const data = await response.json();
+
+    return {
+      id: data.id,
+      email: data.email,
+      name: data.name,
+      picture: data.picture,
+    };
+  }
+}
+
+export const oauthService = new OAuthService();

package/src/auth/rbac.ts

@@ -0,0 +1,82 @@
+import { Role, Permission, RolePermissions, DEFAULT_PERMISSIONS } from './types';
+
+export class RBACService {
+  private permissions: RolePermissions;
+
+  constructor(permissions: RolePermissions = DEFAULT_PERMISSIONS) {
+    this.permissions = permissions;
+  }
+
+  setPermissions(permissions: RolePermissions): void {
+    this.permissions = permissions;
+  }
+
+  addPermission(role: Role, permission: Permission): void {
+    if (!this.permissions[role]) {
+      this.permissions[role] = [];
+    }
+    if (!this.permissions[role].includes(permission)) {
+      this.permissions[role].push(permission);
+    }
+  }
+
+  removePermission(role: Role, permission: Permission): void {
+    if (this.permissions[role]) {
+      this.permissions[role] = this.permissions[role].filter(p => p !== permission);
+    }
+  }
+
+  getPermissions(role: Role): Permission[] {
+    return this.permissions[role] || [];
+  }
+
+  hasPermission(role: Role, requiredPermission: Permission): boolean {
+    const rolePermissions = this.getPermissions(role);
+    
+    if (rolePermissions.includes('*')) {
+      return true;
+    }
+
+    if (rolePermissions.includes(requiredPermission)) {
+      return true;
+    }
+
+    const [requiredAction, requiredScope] = requiredPermission.split(':');
+    
+    for (const perm of rolePermissions) {
+      const [action, scope] = perm.split(':');
+      
+      if (action === '*' && (scope === '*' || scope === requiredScope)) {
+        return true;
+      }
+      
+      if (action === requiredAction && (scope === '*' || scope === requiredScope)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  hasRole(userRole: Role, requiredRole: Role): boolean {
+    const hierarchy: Role[] = ['guest', 'user', 'admin'];
+    const userIndex = hierarchy.indexOf(userRole as any);
+    const requiredIndex = hierarchy.indexOf(requiredRole as any);
+    
+    if (userIndex === -1 || requiredIndex === -1) {
+      return userRole === requiredRole;
+    }
+    
+    return userIndex >= requiredIndex;
+  }
+
+  authorize(permission: Permission) {
+    return (role: Role): boolean => this.hasPermission(role, permission);
+  }
+
+  authorizeRole(requiredRole: Role) {
+    return (role: Role): boolean => this.hasRole(role, requiredRole);
+  }
+}
+
+export const rbacService = new RBACService();

package/src/auth/types.ts

@@ -0,0 +1,69 @@
+export type Role = 'admin' | 'user' | 'guest' | string;
+
+export interface User {
+  id: string;
+  email: string;
+  password?: string;
+  role: Role;
+  name?: string;
+  picture?: string;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+export interface JWTPayload {
+  userId: string;
+  email: string;
+  role: Role;
+}
+
+export interface TokenPair {
+  accessToken: string;
+  refreshToken: string;
+}
+
+export interface AuthOptions {
+  jwtSecret?: string;
+  jwtExpiresIn?: string;
+  refreshSecret?: string;
+  refreshExpiresIn?: string;
+  googleClientId?: string;
+  googleClientSecret?: string;
+  googleRedirectUri?: string;
+}
+
+export interface AuthUserRequest extends Request {
+  user?: JWTPayload;
+}
+
+export type Permission = string;
+
+export interface RolePermissions {
+  [role: string]: Permission[];
+}
+
+export const DEFAULT_PERMISSIONS: RolePermissions = {
+  admin: ['*'],
+  user: ['read', 'write:own'],
+  guest: ['read:public'],
+};
+
+export interface LoginCredentials {
+  email: string;
+  password: string;
+}
+
+export interface RegisterData extends LoginCredentials {
+  name?: string;
+  role?: Role;
+}
+
+export interface OAuthProvider {
+  name: string;
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  authorizationUrl: string;
+  tokenUrl: string;
+  userInfoUrl: string;
+}

package/src/config/index.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+
+export const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.string().default('3000'),
+  DATABASE_URL: z.string().optional(),
+  REDIS_URL: z.string().default('redis://localhost:6379'),
+  JWT_SECRET: z.string().min(32).optional(),
+  JWT_EXPIRES_IN: z.string().default('7d'),
+  JWT_REFRESH_SECRET: z.string().min(32).optional(),
+  JWT_REFRESH_EXPIRES_IN: z.string().default('30d'),
+  GOOGLE_CLIENT_ID: z.string().optional(),
+  GOOGLE_CLIENT_SECRET: z.string().optional(),
+  GOOGLE_REDIRECT_URI: z.string().optional(),
+  SMTP_HOST: z.string().optional(),
+  SMTP_PORT: z.string().default('587'),
+  SMTP_USER: z.string().optional(),
+  SMTP_PASS: z.string().optional(),
+  SMTP_FROM: z.string().optional(),
+  TWILIO_ACCOUNT_SID: z.string().optional(),
+  TWILIO_AUTH_TOKEN: z.string().optional(),
+  TWILIO_PHONE_NUMBER: z.string().optional(),
+  SLACK_WEBHOOK_URL: z.string().optional(),
+  RATE_LIMIT_WINDOW: z.string().default('1m'),
+  RATE_LIMIT_LIMIT: z.string().default('100'),
+  LOG_LEVEL: z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info'),
+});
+
+export type EnvConfig = z.infer<typeof envSchema>;
+
+export interface ConfigOptions {
+  schema?: z.ZodSchema;
+  envPath?: string;
+  validate?: boolean;
+}
+
+class ConfigManager {
+  private config: EnvConfig | null = null;
+  private schema: z.ZodSchema;
+  private validate: boolean;
+
+  constructor(options: ConfigOptions = {}) {
+    this.schema = options.schema || envSchema;
+    this.validate = options.validate ?? true;
+  }
+
+  load(): EnvConfig {
+    if (this.config) return this.config;
+
+    const env: Record<string, string | undefined> = {};
+    
+    for (const key of Object.keys(this.schema.shape)) {
+      env[key] = process.env[key];
+    }
+
+    if (this.validate) {
+      const result = this.schema.safeParse(env);
+      if (!result.success) {
+        const errors = result.error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
+        throw new Error(`Config validation failed: ${errors}`);
+      }
+      this.config = result.data;
+    } else {
+      this.config = env as EnvConfig;
+    }
+
+    return this.config;
+  }
+
+  get<K extends keyof EnvConfig>(key: K): EnvConfig[K] {
+    if (!this.config) this.load();
+    return this.config![key];
+  }
+
+  int(key: keyof EnvConfig): number {
+    const value = this.get(key);
+    if (typeof value === 'string') return parseInt(value, 10);
+    return Number(value);
+  }
+
+  bool(key: keyof EnvConfig): boolean {
+    const value = this.get(key);
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'string') return value.toLowerCase() === 'true';
+    return Boolean(value);
+  }
+
+  isProduction(): boolean {
+    return this.get('NODE_ENV') === 'production';
+  }
+
+  isDevelopment(): boolean {
+    return this.get('NODE_ENV') === 'development';
+  }
+
+  isTest(): boolean {
+    return this.get('NODE_ENV') === 'test';
+  }
+
+  getAll(): EnvConfig {
+    if (!this.config) this.load();
+    return this.config!;
+  }
+}
+
+const globalConfig = new ConfigManager();
+
+export const config = {
+  load: () => globalConfig.load(),
+  get: <K extends keyof EnvConfig>(key: K) => globalConfig.get(key),
+  int: (key: keyof EnvConfig) => globalConfig.int(key),
+  bool: (key: keyof EnvConfig) => globalConfig.bool(key),
+  isProduction: () => globalConfig.isProduction(),
+  isDevelopment: () => globalConfig.isDevelopment(),
+  isTest: () => globalConfig.isTest(),
+  getAll: () => globalConfig.getAll(),
+  create: (options?: ConfigOptions) => new ConfigManager(options),
+};
+
+export default config;

package/src/index.ts

@@ -0,0 +1,16 @@
+export { AuthService, createAuth, auth, Auth } from './auth';
+export { QueueManager, createQueue, queue } from './queue';
+export { notify, notification } from './notifications';
+export { logger } from './logger';
+export { rateLimit, createRateLimiter } from './rate-limit';
+export { config } from './config';
+export { ResponseHelper, response } from './response';
+export { createApp, createExpressApp, SaaSAppBuilder, PluginManager, Plugin, AppOptions } from './plugin';
+
+export { AuthOptions, User, JWTPayload, TokenPair, LoginCredentials, RegisterData, Role, Permission, RolePermissions } from './auth/types';
+export { QueueOptions, JobData, JobProcessor } from './queue';
+export { EmailOptions, SMSOptions, WebhookOptions, SlackOptions } from './notifications';
+export { LoggerConfig, LogLevel } from './logger';
+export { RateLimitOptions } from './rate-limit';
+export { EnvConfig, ConfigOptions } from './config';
+export { ApiResponse, PaginatedResponse, ErrorResponse } from './response';

package/src/logger/index.ts

@@ -0,0 +1,110 @@
+import pino, { Logger, LoggerOptions, Bindings } from 'pino';
+import { config } from '../config';
+
+export type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+
+export interface LoggerConfig extends Partial<LoggerOptions> {
+  level?: LogLevel;
+  name?: string;
+  prettyPrint?: boolean;
+}
+
+export interface RequestLoggerOptions {
+  logLevel?: LogLevel;
+  autoLogging?: boolean;
+}
+
+class LoggerManager {
+  private loggers: Map<string, Logger> = new Map();
+  private defaultLogger: Logger;
+
+  constructor() {
+    const level = (config.get('LOG_LEVEL') as LogLevel) || 'info';
+    this.defaultLogger = pino({
+      level,
+      name: 'saas-backend-kit',
+      formatters: {
+        bindings: (bindings: Bindings) => ({
+          ...bindings,
+          service: 'saas-backend-kit',
+        }),
+      },
+    });
+  }
+
+  createLogger(options: LoggerConfig = {}): Logger {
+    const name = options.name || 'default';
+    
+    if (this.loggers.has(name)) {
+      return this.loggers.get(name)!;
+    }
+
+    const level = options.level || (config.get('LOG_LEVEL') as LogLevel) || 'info';
+    
+    const logger = pino({
+      level,
+      name: options.name,
+      ...options,
+    });
+
+    this.loggers.set(name, logger);
+    return logger;
+  }
+
+  getLogger(name?: string): Logger {
+    if (name) {
+      return this.loggers.get(name) || this.defaultLogger;
+    }
+    return this.defaultLogger;
+  }
+
+  child(bindings: Bindings, options?: { name?: string }): Logger {
+    const name = options?.name || 'child';
+    const parent = options?.name ? this.getLogger(name) : this.defaultLogger;
+    return parent.child(bindings);
+  }
+}
+
+const loggerManager = new LoggerManager();
+
+export const logger = {
+  info: (message: string, ...args: unknown[]) => loggerManager.getLogger().info(message, ...args),
+  warn: (message: string, ...args: unknown[]) => loggerManager.getLogger().warn(message, ...args),
+  error: (message: string, ...args: unknown[]) => loggerManager.getLogger().error(message, ...args),
+  debug: (message: string, ...args: unknown[]) => loggerManager.getLogger().debug(message, ...args),
+  trace: (message: string, ...args: unknown[]) => loggerManager.getLogger().trace(message, ...args),
+  fatal: (message: string, ...args: unknown[]) => loggerManager.getLogger().fatal(message, ...args),
+  child: (bindings: Bindings, options?: { name?: string }) => loggerManager.child(bindings, options),
+  create: (options?: LoggerConfig) => loggerManager.createLogger(options),
+  get: (name?: string) => loggerManager.getLogger(name),
+};
+
+export function createRequestLogger(options: RequestLoggerOptions = {}) {
+  const logLevel = options.logLevel || 'info';
+  const logger = loggerManager.getLogger('http');
+
+  return function requestLogger(
+    req: { method: string; url: string; headers: Record<string, string | string[] | undefined> },
+    res: { statusCode: number; statusMessage?: string },
+    elapsed: number
+  ) {
+    const log = logger.child({
+      method: req.method,
+      url: req.url,
+      status: res.statusCode,
+      responseTime: elapsed,
+      ip: req.headers['x-forwarded-for'] || req.headers['x-real-ip'] || 'unknown',
+      userAgent: req.headers['user-agent'],
+    });
+
+    if (res.statusCode >= 500) {
+      log.error(`Request completed`);
+    } else if (res.statusCode >= 400) {
+      log.warn(`Request completed`);
+    } else {
+      log.info(`Request completed`);
+    }
+  };
+}
+
+export default logger;