saas-backend-kit 1.0.0

package/src/rate-limit/express.ts

@@ -0,0 +1,144 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+import { config } from '../config';
+
+export interface RateLimitOptions {
+  window?: string;
+  limit?: number;
+  keyGenerator?: (req: Request) => string;
+  handler?: (req: Request, res: Response) => void;
+  skipSuccessfulRequests?: boolean;
+  skipFailedRequests?: boolean;
+  skip?: (req: Request) => boolean;
+}
+
+interface RateLimitRecord {
+  count: number;
+  resetTime: number;
+}
+
+class InMemoryRateLimiter {
+  private store: Map<string, RateLimitRecord> = new Map();
+  private cleanupInterval: NodeJS.Timeout;
+
+  constructor() {
+    this.cleanupInterval = setInterval(() => this.cleanup(), 60000);
+  }
+
+  private cleanup(): void {
+    const now = Date.now();
+    for (const [key, record] of this.store.entries()) {
+      if (record.resetTime < now) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  increment(key: string, windowMs: number): RateLimitRecord {
+    const now = Date.now();
+    const record = this.store.get(key);
+
+    if (!record || record.resetTime < now) {
+      const resetTime = now + windowMs;
+      this.store.set(key, { count: 1, resetTime });
+      return { count: 1, resetTime };
+    }
+
+    record.count++;
+    return record;
+  }
+
+  get(key: string): RateLimitRecord | undefined {
+    return this.store.get(key);
+  }
+
+  destroy(): void {
+    clearInterval(this.cleanupInterval);
+  }
+}
+
+class RateLimiter {
+  private options: Required<RateLimitOptions>;
+  private store: InMemoryRateLimiter;
+
+  constructor(options: RateLimitOptions = {}) {
+    const defaultWindow = config.get('RATE_LIMIT_WINDOW') || '1m';
+    const defaultLimit = parseInt(config.get('RATE_LIMIT_LIMIT') || '100', 10);
+
+    this.options = {
+      window: options.window || defaultWindow,
+      limit: options.limit || defaultLimit,
+      keyGenerator: options.keyGenerator || ((req: Request) => req.ip || 'unknown'),
+      handler: options.handler || this.defaultHandler,
+      skipSuccessfulRequests: options.skipSuccessfulRequests || false,
+      skipFailedRequests: options.skipFailedRequests || false,
+      skip: options.skip || (() => false),
+    };
+
+    this.store = new InMemoryRateLimiter();
+  }
+
+  private getWindowMs(): number {
+    const window = this.options.window;
+    const match = window.match(/^(\d+)(s|m|h|d)$/);
+    if (!match) return 60000;
+
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+
+    switch (unit) {
+      case 's': return value * 1000;
+      case 'm': return value * 60 * 1000;
+      case 'h': return value * 60 * 60 * 1000;
+      case 'd': return value * 24 * 60 * 60 * 1000;
+      default: return 60000;
+    }
+  }
+
+  private defaultHandler(req: Request, res: Response): void {
+    res.status(429).json({
+      error: 'Too many requests',
+      message: `Rate limit exceeded. Please try again later.`,
+    });
+  }
+
+  middleware(): RequestHandler {
+    const windowMs = this.getWindowMs();
+
+    return (req: Request, res: Response, next: NextFunction) => {
+      if (this.options.skip(req)) {
+        return next();
+      }
+
+      const key = this.options.keyGenerator(req);
+      const record = this.store.increment(key, windowMs);
+
+      const remaining = Math.max(0, this.options.limit - record.count);
+      const resetTime = new Date(record.resetTime);
+
+      res.setHeader('X-RateLimit-Limit', this.options.limit);
+      res.setHeader('X-RateLimit-Remaining', remaining);
+      res.setHeader('X-RateLimit-Reset', Math.ceil(record.resetTime / 1000));
+
+      if (record.count > this.options.limit) {
+        return this.options.handler(req, res);
+      }
+
+      next();
+    };
+  }
+
+  destroy(): void {
+    this.store.destroy();
+  }
+}
+
+export function rateLimit(options: RateLimitOptions = {}): RequestHandler {
+  const limiter = new RateLimiter(options);
+  return limiter.middleware();
+}
+
+export function createRateLimiter(options: RateLimitOptions): RateLimiter {
+  return new RateLimiter(options);
+}
+
+export default rateLimit;

package/src/rate-limit/fastify.ts

@@ -0,0 +1,47 @@
+import { FastifyInstance, FastifyRequest, FastifyReply, HookHandlerDoneFunction } from 'fastify';
+import { RateLimitOptions, InMemoryRateLimiter } from './express';
+
+export function registerRateLimitPlugin(fastify: FastifyInstance, options: RateLimitOptions = {}, done: HookHandlerDoneFunction) {
+  const limiter = new (require('./express').createRateLimiter.constructor)(options);
+  
+  fastify.addHook('onRequest', async (request: FastifyRequest, reply: FastifyReply) => {
+    const key = options.keyGenerator 
+      ? options.keyGenerator(request.raw as any)
+      : request.ip || 'unknown';
+    
+    const windowMs = parseWindowMs(options.window || '1m');
+    const record = (limiter as any).store.increment(key, windowMs);
+    const limit = options.limit || 100;
+    const remaining = Math.max(0, limit - record.count);
+
+    reply.header('X-RateLimit-Limit', limit);
+    reply.header('X-RateLimit-Remaining', remaining);
+    reply.header('X-RateLimit-Reset', Math.ceil(record.resetTime / 1000));
+
+    if (record.count > limit) {
+      reply.status(429).send({
+        error: 'Too many requests',
+        message: 'Rate limit exceeded. Please try again later.',
+      });
+      return reply;
+    }
+  });
+
+  done();
+}
+
+function parseWindowMs(window: string): number {
+  const match = window.match(/^(\d+)(s|m|h|d)$/);
+  if (!match) return 60000;
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+
+  switch (unit) {
+    case 's': return value * 1000;
+    case 'm': return value * 60 * 1000;
+    case 'h': return value * 60 * 60 * 1000;
+    case 'd': return value * 24 * 60 * 60 * 1000;
+    default: return 60000;
+  }
+}

package/src/rate-limit/index.ts

@@ -0,0 +1,2 @@
+export * from './express';
+export * from './fastify';

package/src/response/index.ts

@@ -0,0 +1,197 @@
+import { Response } from 'express';
+
+export interface ApiResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  message?: string;
+  meta?: {
+    page?: number;
+    limit?: number;
+    total?: number;
+    totalPages?: number;
+  };
+}
+
+export interface PaginatedResponse<T> extends ApiResponse<T> {
+  meta: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+  };
+}
+
+export interface ErrorResponse {
+  success: false;
+  error: string;
+  code?: string;
+  details?: Record<string, unknown>;
+}
+
+export class ResponseHelper {
+  static success<T>(res: Response, data?: T, message?: string, statusCode: number = 200): Response {
+    const response: ApiResponse<T> = {
+      success: true,
+      data,
+      message,
+    };
+    return res.status(statusCode).json(response);
+  }
+
+  static created<T>(res: Response, data?: T, message: string = 'Resource created'): Response {
+    return this.success(res, data, message, 201);
+  }
+
+  static updated<T>(res: Response, data?: T, message: string = 'Resource updated'): Response {
+    return this.success(res, data, message, 200);
+  }
+
+  static deleted(res: Response, message: string = 'Resource deleted'): Response {
+    return this.success(res, null, message, 200);
+  }
+
+  static error(
+    res: Response,
+    error: string,
+    statusCode: number = 400,
+    code?: string,
+    details?: Record<string, unknown>
+  ): Response {
+    const response: ErrorResponse = {
+      success: false,
+      error,
+      code,
+      ...(details && { details }),
+    };
+    return res.status(statusCode).json(response);
+  }
+
+  static badRequest(res: Response, error: string = 'Bad request', code?: string): Response {
+    return this.error(res, error, 400, code);
+  }
+
+  static unauthorized(res: Response, error: string = 'Unauthorized', code?: string): Response {
+    return this.error(res, error, 401, code);
+  }
+
+  static forbidden(res: Response, error: string = 'Forbidden', code?: string): Response {
+    return this.error(res, error, 403, code);
+  }
+
+  static notFound(res: Response, error: string = 'Resource not found', code?: string): Response {
+    return this.error(res, error, 404, code);
+  }
+
+  static conflict(res: Response, error: string = 'Conflict', code?: string): Response {
+    return this.error(res, error, 409, code);
+  }
+
+  static validationError(res: Response, error: string, details?: Record<string, unknown>): Response {
+    return this.error(res, error, 422, 'VALIDATION_ERROR', details);
+  }
+
+  static internalError(res: Response, error: string = 'Internal server error'): Response {
+    return this.error(res, error, 500, 'INTERNAL_ERROR');
+  }
+
+  static paginated<T>(
+    res: Response,
+    data: T[],
+    page: number,
+    limit: number,
+    total: number
+  ): Response<PaginatedResponse<T>> {
+    const totalPages = Math.ceil(total / limit);
+    const response: PaginatedResponse<T> = {
+      success: true,
+      data,
+      meta: {
+        page,
+        limit,
+        total,
+        totalPages,
+      },
+    };
+    return res.status(200).json(response);
+  }
+
+  static noContent(res: Response): Response {
+    return res.status(204).send();
+  }
+}
+
+declare global {
+  namespace Express {
+    interface Response {
+      success<T>(data?: T, message?: string, statusCode?: number): Response;
+      created<T>(data?: T, message?: string): Response;
+      updated<T>(data?: T, message?: string): Response;
+      deleted(message?: string): Response;
+      error(error: string, statusCode?: number, code?: string, details?: Record<string, unknown>): Response;
+      badRequest(error?: string, code?: string): Response;
+      unauthorized(error?: string, code?: string): Response;
+      forbidden(error?: string, code?: string): Response;
+      notFound(error?: string, code?: string): Response;
+      conflict(error?: string, code?: string): Response;
+      validationError(error: string, details?: Record<string, unknown>): Response;
+      internalError(error?: string): Response;
+      paginated<T>(data: T[], page: number, limit: number, total: number): Response;
+    }
+  }
+}
+
+Response.prototype.success = function <T>(data?: T, message?: string, statusCode: number = 200) {
+  return ResponseHelper.success(this, data, message, statusCode);
+};
+
+Response.prototype.created = function <T>(data?: T, message?: string) {
+  return ResponseHelper.created(this, data, message);
+};
+
+Response.prototype.updated = function <T>(data?: T, message?: string) {
+  return ResponseHelper.updated(this, data, message);
+};
+
+Response.prototype.deleted = function (message?: string) {
+  return ResponseHelper.deleted(this, message);
+};
+
+Response.prototype.error = function (error: string, statusCode: number = 400, code?: string, details?: Record<string, unknown>) {
+  return ResponseHelper.error(this, error, statusCode, code, details);
+};
+
+Response.prototype.badRequest = function (error?: string, code?: string) {
+  return ResponseHelper.badRequest(this, error, code);
+};
+
+Response.prototype.unauthorized = function (error?: string, code?: string) {
+  return ResponseHelper.unauthorized(this, error, code);
+};
+
+Response.prototype.forbidden = function (error?: string, code?: string) {
+  return ResponseHelper.forbidden(this, error, code);
+};
+
+Response.prototype.notFound = function (error?: string, code?: string) {
+  return ResponseHelper.notFound(this, error, code);
+};
+
+Response.prototype.conflict = function (error?: string, code?: string) {
+  return ResponseHelper.conflict(this, error, code);
+};
+
+Response.prototype.validationError = function (error: string, details?: Record<string, unknown>) {
+  return ResponseHelper.validationError(this, error, details);
+};
+
+Response.prototype.internalError = function (error?: string) {
+  return ResponseHelper.internalError(this, error);
+};
+
+Response.prototype.paginated = function <T>(data: T[], page: number, limit: number, total: number) {
+  return ResponseHelper.paginated(this, data, page, limit, total);
+};
+
+export const response = ResponseHelper;
+export default ResponseHelper;

package/src/utils/index.ts

@@ -0,0 +1,180 @@
+import crypto from 'crypto';
+
+export function generateId(length: number = 16): string {
+  return crypto.randomBytes(length).toString('hex');
+}
+
+export function hashString(input: string, algorithm: string = 'sha256'): string {
+  return crypto.createHash(algorithm).update(input).digest('hex');
+}
+
+export function timingSafeEqual(a: string, b: string): boolean {
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  
+  if (bufA.length !== bufB.length) {
+    return false;
+  }
+  
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+export function generateToken(length: number = 32): string {
+  return crypto.randomBytes(length).toString('base64url');
+}
+
+export function generateApiKey(prefix: string = 'sk'): string {
+  const timestamp = Date.now().toString(36);
+  const random = crypto.randomBytes(24).toString('hex');
+  return `${prefix}_${timestamp}_${random}`;
+}
+
+export class Cache<T> {
+  private store: Map<string, { value: T; expiresAt: number }> = new Map();
+  
+  set(key: string, value: T, ttlMs: number = 60000): void {
+    const expiresAt = Date.now() + ttlMs;
+    this.store.set(key, { value, expiresAt });
+  }
+
+  get(key: string): T | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+    
+    return entry.value;
+  }
+
+  has(key: string): boolean {
+    return this.get(key) !== undefined;
+  }
+
+  delete(key: string): boolean {
+    return this.store.delete(key);
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (now > entry.expiresAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export function retry<T>(
+  fn: () => Promise<T>,
+  options: { maxAttempts?: number; delayMs?: number; backoff?: boolean } = {}
+): Promise<T> {
+  const { maxAttempts = 3, delayMs = 1000, backoff = true } = options;
+  
+  return new Promise(async (resolve, reject) => {
+    let lastError: Error | undefined;
+    
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const result = await fn();
+        return resolve(result);
+      } catch (error) {
+        lastError = error as Error;
+        
+        if (attempt < maxAttempts) {
+          const delay = backoff ? delayMs * Math.pow(2, attempt - 1) : delayMs;
+          await sleep(delay);
+        }
+      }
+    }
+    
+    reject(lastError);
+  });
+}
+
+export function debounce<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  delayMs: number
+): (...args: Parameters<T>) => void {
+  let timeoutId: NodeJS.Timeout;
+  
+  return (...args: Parameters<T>) => {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => fn(...args), delayMs);
+  };
+}
+
+export function throttle<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  limitMs: number
+): (...args: Parameters<T>) => void {
+  let lastRun = 0;
+  
+  return (...args: Parameters<T>) => {
+    const now = Date.now();
+    if (now - lastRun >= limitMs) {
+      lastRun = now;
+      fn(...args);
+    }
+  };
+}
+
+export function parseQueryInt(value: string | undefined, defaultValue: number): number {
+  if (!value) return defaultValue;
+  const parsed = parseInt(value, 10);
+  return isNaN(parsed) ? defaultValue : parsed;
+}
+
+export function parseQueryBool(value: string | undefined, defaultValue: boolean): boolean {
+  if (!value) return defaultValue;
+  return value.toLowerCase() === 'true';
+}
+
+export function sanitizeObject<T extends Record<string, unknown>>(
+  obj: T,
+  allowedKeys: string[]
+): Partial<T> {
+  const sanitized: Partial<T> = {};
+  
+  for (const key of allowedKeys) {
+    if (key in obj) {
+      sanitized[key as keyof T] = obj[key];
+    }
+  }
+  
+  return sanitized;
+}
+
+export function omit<T extends Record<string, unknown>, K extends keyof T>(
+  obj: T,
+  keys: K[]
+): Omit<T, K> {
+  const result = { ...obj };
+  for (const key of keys) {
+    delete result[key];
+  }
+  return result;
+}
+
+export function pick<T extends Record<string, unknown>, K extends keyof T>(
+  obj: T,
+  keys: K[]
+): Pick<T, K> {
+  const result = {} as Pick<T, K>;
+  for (const key of keys) {
+    if (key in obj) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "noImplicitAny": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "composite": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "examples"]
+}

package/tsup.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: {
+    'index': 'src/index.ts',
+    'auth/index': 'src/auth/index.ts',
+    'queue/index': 'src/queue/index.ts',
+    'notifications/index': 'src/notifications/index.ts',
+    'logger/index': 'src/logger/index.ts',
+    'rate-limit/index': 'src/rate-limit/index.ts',
+    'config/index': 'src/config/index.ts',
+    'response/index': 'src/response/index.ts',
+  },
+  format: ['cjs', 'esm'],
+  dts: false,
+  splitting: false,
+  sourcemap: true,
+  clean: false,
+  external: ['express', 'fastify', 'ioredis', 'bullmq'],
+  treeshake: true,
+  exports: {
+    namedExports: true,
+  },
+});