saas-backend-kit 1.0.0

package/src/notifications/index.ts

@@ -0,0 +1,262 @@
+import nodemailer, { Transporter, SendMailOptions } from 'nodemailer';
+import { config } from '../config';
+import { logger } from '../logger';
+
+export interface EmailOptions {
+  to: string | string[];
+  subject: string;
+  text?: string;
+  html?: string;
+  template?: string;
+  templateData?: Record<string, unknown>;
+  from?: string;
+  cc?: string | string[];
+  bcc?: string | string[];
+  attachments?: Array<{
+    filename: string;
+    content?: Buffer | string;
+    path?: string;
+    contentType?: string;
+  }>;
+}
+
+export interface SMSOptions {
+  to: string;
+  message: string;
+  from?: string;
+}
+
+export interface WebhookOptions {
+  url: string;
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH';
+  headers?: Record<string, string>;
+  body?: unknown;
+  timeout?: number;
+}
+
+export interface SlackOptions {
+  text?: string;
+  blocks?: Array<{
+    type: string;
+    text?: { type: string; text: string; emoji?: boolean };
+    elements?: Array<{ type: string; text?: { type: string; text: string } }>;
+    accessory?: { type: string; image_url?: string; alt_text?: string };
+  }>;
+  channel?: string;
+  username?: string;
+  iconEmoji?: string;
+}
+
+export interface NotificationTransporter {
+  email: Transporter;
+  twilio?: {
+    accountSid: string;
+    authToken: string;
+    phoneNumber: string;
+  };
+  slack?: {
+    webhookUrl: string;
+  };
+}
+
+class EmailService {
+  private transporter: Transporter | null = null;
+  private from: string;
+
+  constructor() {
+    this.from = config.get('SMTP_FROM') || 'noreply@example.com';
+    this.initialize();
+  }
+
+  private initialize(): void {
+    const host = config.get('SMTP_HOST');
+    const port = parseInt(config.get('SMTP_PORT') || '587', 10);
+    const user = config.get('SMTP_USER');
+    const pass = config.get('SMTP_PASS');
+
+    if (host && user && pass) {
+      this.transporter = nodemailer.createTransport({
+        host,
+        port,
+        secure: port === 465,
+        auth: {
+          user,
+          pass,
+        },
+      });
+      logger.info('Email service initialized');
+    }
+  }
+
+  setTransporter(transporter: Transporter): void {
+    this.transporter = transporter;
+  }
+
+  async send(options: EmailOptions): Promise<{ messageId: string }> {
+    if (!this.transporter) {
+      logger.warn('Email transporter not configured, skipping email');
+      return { messageId: 'mock-message-id' };
+    }
+
+    const mailOptions: SendMailOptions = {
+      from: options.from || this.from,
+      to: Array.isArray(options.to) ? options.to.join(', ') : options.to,
+      subject: options.subject,
+      text: options.text,
+      html: options.html || this.renderTemplate(options.template, options.templateData),
+      cc: options.cc,
+      bcc: options.bcc,
+      attachments: options.attachments,
+    };
+
+    const result = await this.transporter.sendMail(mailOptions);
+    logger.info(`Email sent to ${options.to}`, { messageId: result.messageId });
+    return { messageId: result.messageId };
+  }
+
+  private renderTemplate(templateName?: string, data?: Record<string, unknown>): string | undefined {
+    if (!templateName || !data) return undefined;
+
+    const templates: Record<string, (data: Record<string, unknown>) => string> = {
+      welcome: (data) => `
+        <h1>Welcome, ${data.name || 'User'}!</h1>
+        <p>Thank you for joining ${data.appName || 'our platform'}.</p>
+        <p>Get started by verifying your email.</p>
+      `,
+      passwordReset: (data) => `
+        <h1>Password Reset</h1>
+        <p>Click <a href="${data.resetUrl}">here</a> to reset your password.</p>
+        <p>This link expires in ${data.expiry || '1 hour'}.</p>
+      `,
+      verification: (data) => `
+        <h1>Verify Your Email</h1>
+        <p>Click <a href="${data.verifyUrl}">here</a> to verify your email.</p>
+      `,
+    };
+
+    const template = templates[templateName];
+    return template ? template(data) : undefined;
+  }
+}
+
+class SMSService {
+  private accountSid: string;
+  private authToken: string;
+  private phoneNumber: string;
+  private initialized: boolean = false;
+
+  constructor() {
+    this.accountSid = config.get('TWILIO_ACCOUNT_SID') || '';
+    this.authToken = config.get('TWILIO_AUTH_TOKEN') || '';
+    this.phoneNumber = config.get('TWILIO_PHONE_NUMBER') || '';
+    this.initialized = !!(this.accountSid && this.authToken && this.phoneNumber);
+  }
+
+  async send(options: SMSOptions): Promise<{ sid: string }> {
+    if (!this.initialized) {
+      logger.warn('Twilio not configured, skipping SMS');
+      return { sid: 'mock-sid' };
+    }
+
+    try {
+      const twilio = await import('twilio');
+      const client = twilio.default(this.accountSid, this.authToken);
+
+      const result = await client.messages.create({
+        body: options.message,
+        from: options.from || this.phoneNumber,
+        to: options.to,
+      });
+
+      logger.info(`SMS sent to ${options.to}`, { sid: result.sid });
+      return { sid: result.sid };
+    } catch (error) {
+      logger.error('Failed to send SMS', { error });
+      throw error;
+    }
+  }
+}
+
+class WebhookService {
+  async send(options: WebhookOptions): Promise<{ status: number; body: unknown }> {
+    const response = await fetch(options.url, {
+      method: options.method || 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...options.headers,
+      },
+      body: options.body ? JSON.stringify(options.body) : undefined,
+      signal: options.timeout ? AbortSignal.timeout(options.timeout) : undefined,
+    });
+
+    const body = await response.json().catch(() => null);
+    logger.info(`Webhook sent to ${options.url}`, { status: response.status });
+    return { status: response.status, body };
+  }
+}
+
+class SlackService {
+  private webhookUrl: string;
+
+  constructor() {
+    this.webhookUrl = config.get('SLACK_WEBHOOK_URL') || '';
+  }
+
+  setWebhookUrl(url: string): void {
+    this.webhookUrl = url;
+  }
+
+  async send(options: SlackOptions): Promise<{ ok: boolean }> {
+    if (!this.webhookUrl) {
+      logger.warn('Slack webhook not configured, skipping message');
+      return { ok: false };
+    }
+
+    const payload = {
+      text: options.text,
+      blocks: options.blocks,
+      channel: options.channel,
+      username: options.username,
+      icon_emoji: options.iconEmoji,
+    };
+
+    const response = await fetch(this.webhookUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+
+    const ok = response.ok;
+    if (ok) {
+      logger.info('Slack message sent');
+    } else {
+      logger.error('Failed to send Slack message');
+    }
+    return { ok };
+  }
+}
+
+class NotificationService {
+  email: EmailService;
+  sms: SMSService;
+  webhook: WebhookService;
+  slack: SlackService;
+
+  constructor() {
+    this.email = new EmailService();
+    this.sms = new SMSService();
+    this.webhook = new WebhookService();
+    this.slack = new SlackService();
+  }
+}
+
+export const notify = new NotificationService();
+
+export const notification = {
+  email: (options: EmailOptions) => notify.email.send(options),
+  sms: (options: SMSOptions) => notify.sms.send(options),
+  webhook: (options: WebhookOptions) => notify.webhook.send(options),
+  slack: (options: SlackOptions) => notify.slack.send(options),
+};
+
+export default notification;

package/src/plugin.ts

@@ -0,0 +1,192 @@
+import { Application, Request, Response, NextFunction, RequestHandler } from 'express';
+import { FastifyInstance } from 'fastify';
+import { createAuth, AuthService } from './auth';
+import { createQueue, QueueManager } from './queue';
+import { notify, notification } from './notifications';
+import { logger } from './logger';
+import { rateLimit } from './rate-limit';
+import { config } from './config';
+import { ResponseHelper } from './response';
+
+export interface AppOptions {
+  framework?: 'express' | 'fastify';
+  auth?: boolean | {
+    jwtSecret?: string;
+    jwtExpiresIn?: string;
+    refreshSecret?: string;
+    refreshExpiresIn?: string;
+    googleClientId?: string;
+    googleClientSecret?: string;
+    googleRedirectUri?: string;
+  };
+  queue?: boolean | {
+    redisUrl?: string;
+  };
+  notifications?: boolean;
+  rateLimit?: boolean | {
+    window?: string;
+    limit?: number;
+  };
+  logger?: boolean | {
+    level?: string;
+    prettyPrint?: boolean;
+  };
+  config?: boolean;
+}
+
+export interface Plugin {
+  name: string;
+  initialize: (app: Application | FastifyInstance) => Promise<void> | void;
+  middleware?: RequestHandler[];
+}
+
+class PluginManager {
+  private plugins: Map<string, Plugin> = new Map();
+  private app: Application | FastifyInstance | null = null;
+  private authService: AuthService | null = null;
+  private queueManager: QueueManager | null = null;
+
+  register(plugin: Plugin): void {
+    this.plugins.set(plugin.name, plugin);
+    logger.info(`Plugin "${plugin.name}" registered`);
+  }
+
+  unregister(name: string): void {
+    this.plugins.delete(name);
+    logger.info(`Plugin "${name}" unregistered`);
+  }
+
+  get(name: string): Plugin | undefined {
+    return this.plugins.get(name);
+  }
+
+  getAll(): Plugin[] {
+    return Array.from(this.plugins.values());
+  }
+
+  has(name: string): boolean {
+    return this.plugins.has(name);
+  }
+
+  async initializeAll(app: Application | FastifyInstance): Promise<void> {
+    this.app = app;
+    
+    for (const plugin of this.plugins.values()) {
+      logger.info(`Initializing plugin "${plugin.name}"`);
+      await plugin.initialize(app);
+      
+      if (plugin.middleware && 'use' in app) {
+        for (const mw of plugin.middleware) {
+          (app as Application).use(mw);
+        }
+      }
+    }
+  }
+}
+
+export class SaaSAppBuilder {
+  private options: AppOptions;
+  private pluginManager: PluginManager;
+  private initialized: boolean = false;
+
+  constructor(options: AppOptions = {}) {
+    this.options = options;
+    this.pluginManager = new PluginManager();
+  }
+
+  use(plugin: Plugin): this {
+    this.pluginManager.register(plugin);
+    return this;
+  }
+
+  async initialize(app: Application | FastifyInstance): Promise<void> {
+    if (this.initialized) {
+      throw new Error('App already initialized');
+    }
+
+    config.load();
+
+    if (this.options.logger !== false) {
+      const loggerOptions = typeof this.options.logger === 'object' ? this.options.logger : {};
+      logger.create(loggerOptions);
+    }
+
+    if (this.options.auth !== false) {
+      const authOptions = typeof this.options.auth === 'object' ? this.options.auth : {};
+      this.authService = createAuth(authOptions);
+      await this.authService.initialize();
+      
+      this.pluginManager.register({
+        name: 'auth',
+        initialize: (app) => {
+          if ('use' in app) {
+            (app as Application).use(this.authService!.getMiddleware());
+          }
+        },
+        middleware: [this.authService!.getMiddleware()],
+      });
+    }
+
+    if (this.options.queue !== false) {
+      const queueOptions = typeof this.options.queue === 'object' ? this.options.queue : {};
+      if (queueOptions.redisUrl) {
+        (await import('./queue')).queue.setRedisOptions({ url: queueOptions.redisUrl });
+      }
+      
+      this.pluginManager.register({
+        name: 'queue',
+        initialize: () => {},
+      });
+    }
+
+    if (this.options.rateLimit !== false) {
+      const rateLimitOptions = typeof this.options.rateLimit === 'object' ? this.options.rateLimit : {};
+      
+      this.pluginManager.register({
+        name: 'rate-limit',
+        initialize: (app) => {
+          if ('use' in app) {
+            (app as Application).use(rateLimit(rateLimitOptions));
+          }
+        },
+        middleware: [rateLimit(rateLimitOptions)],
+      });
+    }
+
+    if (this.options.notifications !== false) {
+      this.pluginManager.register({
+        name: 'notifications',
+        initialize: () => {},
+      });
+    }
+
+    await this.pluginManager.initializeAll(app);
+    this.initialized = true;
+    logger.info('SaaS App initialized');
+  }
+
+  getAuth(): AuthService | null {
+    return this.authService;
+  }
+
+  getPluginManager(): PluginManager {
+    return this.pluginManager;
+  }
+}
+
+export function createApp(options: AppOptions = {}): SaaSAppBuilder {
+  return new SaaSAppBuilder(options);
+}
+
+export function createExpressApp(options: AppOptions = {}): Application {
+  const express = require('express');
+  const app = express();
+  
+  const builder = createApp({ ...options, framework: 'express' });
+  builder.initialize(app);
+  
+  return app;
+}
+
+export { PluginManager, Plugin };
+export default createApp;

package/src/queue/index.ts

@@ -0,0 +1,208 @@
+import { Queue, Worker, Job, JobsOptions, WorkerOptions } from 'bullmq';
+import { config } from '../config';
+import { logger } from '../logger';
+
+export interface QueueOptions {
+  name: string;
+  defaultJobOptions?: JobsOptions;
+}
+
+export interface RedisOptions {
+  host?: string;
+  port?: number;
+  password?: string;
+  db?: number;
+  url?: string;
+}
+
+export interface JobData {
+  [key: string]: unknown;
+}
+
+export type JobProcessor = (job: Job<JobData>) => Promise<unknown>;
+
+class QueueManager {
+  private queues: Map<string, Queue> = new Map();
+  private workers: Map<string, Worker> = new Map();
+  private redisOptions: RedisOptions;
+
+  constructor() {
+    const redisUrl = config.get('REDIS_URL');
+    if (redisUrl) {
+      this.redisOptions = { url: redisUrl };
+    } else {
+      this.redisOptions = {
+        host: 'localhost',
+        port: 6379,
+      };
+    }
+  }
+
+  setRedisOptions(options: RedisOptions): void {
+    this.redisOptions = options;
+  }
+
+  createQueue(name: string, options?: Partial<QueueOptions>): Queue {
+    if (this.queues.has(name)) {
+      return this.queues.get(name)!;
+    }
+
+    const queue = new Queue(name, {
+      connection: this.redisOptions as any,
+      defaultJobOptions: options?.defaultJobOptions || {
+        removeOnComplete: 100,
+        removeOnFail: 100,
+      },
+    });
+
+    this.queues.set(name, queue);
+    logger.info(`Queue "${name}" created`);
+
+    return queue;
+  }
+
+  getQueue(name: string): Queue | undefined {
+    return this.queues.get(name);
+  }
+
+  async addJob(
+    queueName: string,
+    jobName: string,
+    data: JobData,
+    options?: JobsOptions
+  ): Promise<Job> {
+    const queue = this.getQueue(queueName) || this.createQueue(queueName);
+    const job = await queue.add(jobName, data, options);
+    logger.debug(`Job "${jobName}" added to queue "${queueName}"`, { jobId: job.id });
+    return job;
+  }
+
+  async addBulkJobs(
+    queueName: string,
+    jobs: Array<{ name: string; data: JobData; options?: JobsOptions }>
+  ): Promise<Job[]> {
+    const queue = this.getQueue(queueName) || this.createQueue(queueName);
+    const bulkJobs = jobs.map(job => ({
+      name: job.name,
+      data: job.data,
+      ...job.options,
+    }));
+    const result = await queue.addBulk(bulkJobs);
+    logger.debug(`${jobs.length} jobs added to queue "${queueName}"`);
+    return result;
+  }
+
+  processJob(
+    queueName: string,
+    processor: JobProcessor,
+    options?: WorkerOptions
+  ): Worker {
+    const queue = this.getQueue(queueName) || this.createQueue(queueName);
+    
+    const worker = new Worker(queueName, async (job) => {
+      logger.debug(`Processing job "${job.name}"`, { jobId: job.id, queue: queueName });
+      return await processor(job);
+    }, {
+      connection: this.redisOptions as any,
+      concurrency: options?.concurrency || 1,
+      ...options,
+    });
+
+    worker.on('completed', (job) => {
+      logger.debug(`Job completed`, { jobId: job.id, queue: queueName });
+    });
+
+    worker.on('failed', (job, err) => {
+      logger.error(`Job failed`, { jobId: job?.id, queue: queueName, error: err.message });
+    });
+
+    worker.on('error', (err) => {
+      logger.error(`Worker error`, { queue: queueName, error: err.message });
+    });
+
+    this.workers.set(queueName, worker);
+    logger.info(`Worker started for queue "${queueName}"`);
+
+    return worker;
+  }
+
+  async getJobCounts(queueName: string): Promise<Record<string, number>> {
+    const queue = this.getQueue(queueName);
+    if (!queue) {
+      return { waiting: 0, active: 0, completed: 0, failed: 0, delayed: 0 };
+    }
+    return await queue.getJobCounts();
+  }
+
+  async getJobs(queueName: string, start: number = 0, end: number = 10): Promise<Job[]> {
+    const queue = this.getQueue(queueName);
+    if (!queue) return [];
+    return await queue.getJobs(['waiting', 'active', 'completed', 'failed'], start, end);
+  }
+
+  async closeQueue(name: string): Promise<void> {
+    const queue = this.queues.get(name);
+    if (queue) {
+      await queue.close();
+      this.queues.delete(name);
+      logger.info(`Queue "${name}" closed`);
+    }
+  }
+
+  async closeWorker(name: string): Promise<void> {
+    const worker = this.workers.get(name);
+    if (worker) {
+      await worker.close();
+      this.workers.delete(name);
+      logger.info(`Worker for queue "${name}" closed`);
+    }
+  }
+
+  async closeAll(): Promise<void> {
+    await Promise.all([
+      ...Array.from(this.queues.values()).map(q => q.close()),
+      ...Array.from(this.workers.values()).map(w => w.close()),
+    ]);
+    this.queues.clear();
+    this.workers.clear();
+    logger.info('All queues and workers closed');
+  }
+}
+
+const queueManager = new QueueManager();
+
+export const createQueue = (name: string, options?: Partial<QueueOptions>): Queue => {
+  return queueManager.createQueue(name, options);
+};
+
+export const addJob = (
+  queueName: string,
+  jobName: string,
+  data: JobData,
+  options?: JobsOptions
+): Promise<Job> => {
+  return queueManager.addJob(queueName, jobName, data, options);
+};
+
+export const processJob = (
+  queueName: string,
+  processor: JobProcessor,
+  options?: WorkerOptions
+): Worker => {
+  return queueManager.processJob(queueName, processor, options);
+};
+
+export const queue = {
+  create: createQueue,
+  add: addJob,
+  process: processJob,
+  get: (name: string) => queueManager.getQueue(name),
+  getJobCounts: (name: string) => queueManager.getJobCounts(name),
+  getJobs: (name: string, start?: number, end?: number) => queueManager.getJobs(name, start, end),
+  close: (name: string) => queueManager.closeQueue(name),
+  closeAll: () => queueManager.closeAll(),
+  setRedisOptions: (options: RedisOptions) => queueManager.setRedisOptions(options),
+};
+
+export { QueueManager };
+export default queue;