create-blitzpack 0.1.0

package/template/apps/api/src/app.ts

@@ -0,0 +1,377 @@
+import cookie from '@fastify/cookie';
+import cors from '@fastify/cors';
+import formbody from '@fastify/formbody';
+import helmet from '@fastify/helmet';
+import rateLimit from '@fastify/rate-limit';
+import { AppError } from '@repo/packages-utils/errors';
+import type { FastifyError, FastifyReply, FastifyRequest } from 'fastify';
+import Fastify from 'fastify';
+import {
+  serializerCompiler,
+  validatorCompiler,
+  type ZodTypeProvider,
+} from 'fastify-type-provider-zod';
+
+import { loadEnv } from '@/config/env';
+import type { RateLimitRole } from '@/config/rate-limit';
+import { RATE_LIMIT_CONFIG } from '@/config/rate-limit';
+import { metricsService } from '@/services/metrics.service';
+
+const env = loadEnv();
+
+export const app = Fastify({
+  logger: {
+    level: 'trace',
+    formatters: {
+      level: (label) => ({ level: label }),
+    },
+    transport:
+      env.NODE_ENV === 'development'
+        ? {
+            target: 'pino-pretty',
+            options: {
+              colorize: true,
+              ignore: 'pid,hostname',
+              singleLine: false,
+              translateTime: 'HH:MM:ss',
+            },
+          }
+        : undefined,
+  },
+  disableRequestLogging: true,
+  requestIdHeader: 'x-request-id',
+  genReqId: () => `req-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+  bodyLimit: 1048576,
+  routerOptions: {
+    ignoreTrailingSlash: true,
+  },
+  onProtoPoisoning: 'error',
+  onConstructorPoisoning: 'error',
+}).withTypeProvider<ZodTypeProvider>();
+
+app.setValidatorCompiler(validatorCompiler);
+app.setSerializerCompiler(serializerCompiler);
+
+await app.register(helmet, {
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      scriptSrc: ["'self'", "'unsafe-inline'"],
+      imgSrc: ["'self'", 'data:', 'https:'],
+    },
+  },
+});
+
+await app.register(cors, {
+  origin: env.FRONTEND_URL,
+  credentials: true,
+  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+  allowedHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
+  exposedHeaders: ['X-Request-ID'],
+});
+
+// @ts-expect-error - Known issue with @fastify/rate-limit type definitions
+await app.register(rateLimit, {
+  global: true,
+  max: async (request: FastifyRequest) => {
+    const session = await request.server.auth.api
+      .getSession({
+        headers: request.headers as unknown as Headers,
+      })
+      .catch(() => null);
+
+    if (!session?.user) {
+      return RATE_LIMIT_CONFIG.anonymous.max;
+    }
+
+    const userWithRole = session.user as typeof session.user & {
+      role?: string;
+    };
+    const role = (userWithRole.role || 'user') as RateLimitRole;
+
+    return RATE_LIMIT_CONFIG[role]?.max || RATE_LIMIT_CONFIG.user.max;
+  },
+  timeWindow: 60 * 1000,
+  keyGenerator: async (request: FastifyRequest) => {
+    const session = await request.server.auth.api
+      .getSession({
+        headers: request.headers as unknown as Headers,
+      })
+      .catch(() => null);
+
+    if (session?.user?.id) {
+      return `user:${session.user.id}`;
+    }
+
+    return `ip:${request.ip}`;
+  },
+  addHeadersOnExceeding: {
+    'X-RateLimit-Limit': true,
+    'X-RateLimit-Remaining': true,
+    'X-RateLimit-Reset': true,
+  },
+  addHeaders: {
+    'X-RateLimit-Limit': true,
+    'X-RateLimit-Remaining': true,
+    'X-RateLimit-Reset': true,
+  },
+  errorResponseBuilder: (request: FastifyRequest) => ({
+    statusCode: 429,
+    error: 'Too Many Requests',
+    message: 'Rate limit exceeded. Please try again later.',
+  }),
+});
+
+await app.register(cookie, {
+  secret: env.COOKIE_SECRET,
+  parseOptions: {},
+});
+
+await app.register(formbody);
+
+const { default: multipartPlugin } = await import('@/plugins/multipart.js');
+await app.register(multipartPlugin);
+
+const { default: loggerPlugin } = await import('@/plugins/logger.js');
+await app.register(loggerPlugin);
+
+const { default: databasePlugin } = await import('@/plugins/database.js');
+await app.register(databasePlugin);
+
+const { default: servicesPlugin } = await import('@/plugins/services.js');
+await app.register(servicesPlugin);
+
+const { default: authPlugin } = await import('@/plugins/auth.js');
+await app.register(authPlugin);
+
+const { default: swaggerPlugin } = await import('@/plugins/swagger.js');
+await app.register(swaggerPlugin);
+
+const { default: scalarPlugin } = await import('@/plugins/scalar.js');
+await app.register(scalarPlugin);
+
+const { default: schedulePlugin } = await import('@/plugins/schedule.js');
+await app.register(schedulePlugin);
+
+const errorHandler = (
+  error: FastifyError,
+  request: FastifyRequest,
+  reply: FastifyReply
+): void => {
+  request.log.error(
+    {
+      err: error,
+      reqId: request.id,
+      url: request.url,
+      method: request.method,
+    },
+    'Request error'
+  );
+
+  if (error instanceof AppError) {
+    void reply.status(error.statusCode).send({
+      error: {
+        message: error.message,
+        code: error.code,
+        ...(error.details && { details: error.details }),
+      },
+    });
+    return;
+  }
+
+  if (error.validation) {
+    void reply.status(400).send({
+      error: {
+        message: 'Validation failed',
+        code: 'VALIDATION_ERROR',
+        details: error.validation,
+      },
+    });
+    return;
+  }
+
+  const isProduction = env.NODE_ENV === 'production';
+  const statusCode = error.statusCode || 500;
+
+  void reply.status(statusCode).send({
+    error: {
+      message:
+        isProduction && statusCode === 500
+          ? 'Internal server error'
+          : error.message || 'An error occurred',
+      code: 'INTERNAL_ERROR',
+    },
+  });
+};
+
+app.setErrorHandler(errorHandler);
+
+app.addHook('onRequest', async (request) => {
+  if (env.LOG_LEVEL === 'detailed' || env.LOG_LEVEL === 'verbose') {
+    request.log = request.log.child({ reqId: request.id });
+  }
+});
+
+app.addHook('onResponse', async (request, reply) => {
+  try {
+    const responseTime = reply.elapsedTime;
+    metricsService.recordRequest(responseTime, reply.statusCode);
+
+    const statusCode = reply.statusCode;
+    const isError = statusCode >= 400;
+    const logMessage = `${request.method} ${request.url} → ${statusCode} (${responseTime.toFixed(2)}ms)`;
+
+    switch (env.LOG_LEVEL) {
+      case 'minimal':
+        if (isError) {
+          request.log.error(
+            {
+              method: request.method,
+              url: request.url,
+              statusCode,
+              responseTime: `${responseTime.toFixed(2)}ms`,
+            },
+            logMessage
+          );
+        }
+        break;
+
+      case 'normal':
+        if (isError) {
+          request.log.error(logMessage);
+        } else {
+          request.log.info(logMessage);
+        }
+        break;
+
+      case 'detailed':
+        if (isError) {
+          request.log.error(
+            {
+              method: request.method,
+              url: request.url,
+              statusCode,
+              responseTime: `${responseTime.toFixed(2)}ms`,
+              ip: request.ip,
+              userAgent: request.headers['user-agent'],
+            },
+            logMessage
+          );
+        } else {
+          request.log.info(
+            {
+              method: request.method,
+              url: request.url,
+              statusCode,
+              responseTime: `${responseTime.toFixed(2)}ms`,
+              ip: request.ip,
+              userAgent: request.headers['user-agent'],
+            },
+            logMessage
+          );
+        }
+        break;
+
+      case 'verbose':
+        if (isError) {
+          request.log.error(
+            {
+              method: request.method,
+              url: request.url,
+              statusCode,
+              responseTime: `${responseTime.toFixed(2)}ms`,
+              ip: request.ip,
+              userAgent: request.headers['user-agent'],
+              req: {
+                params: request.params,
+                query: request.query,
+                headers: request.headers,
+              },
+              res: {
+                headers: reply.getHeaders(),
+              },
+            },
+            logMessage
+          );
+        } else {
+          request.log.info(
+            {
+              method: request.method,
+              url: request.url,
+              statusCode,
+              responseTime: `${responseTime.toFixed(2)}ms`,
+              ip: request.ip,
+              userAgent: request.headers['user-agent'],
+              req: {
+                params: request.params,
+                query: request.query,
+                headers: request.headers,
+              },
+              res: {
+                headers: reply.getHeaders(),
+              },
+            },
+            logMessage
+          );
+        }
+        break;
+    }
+  } catch (error) {
+    console.error('[onResponse hook error]:', error);
+  }
+});
+
+app.get('/health', async (request, reply) => {
+  try {
+    await app.prisma.$queryRaw`SELECT 1`;
+    return {
+      status: 'ok',
+      timestamp: new Date().toISOString(),
+      database: 'connected',
+    };
+  } catch (error) {
+    request.log.error(error, 'Database health check failed');
+    return reply.status(503).send({
+      status: 'error',
+      timestamp: new Date().toISOString(),
+      database: 'disconnected',
+    });
+  }
+});
+
+const { default: usersRoutes } = await import('@/routes/users.js');
+const { default: sessionsRoutes } = await import('@/routes/sessions.js');
+const { default: passwordRoutes } = await import('@/routes/password.js');
+const { default: verificationRoutes } = await import(
+  '@/routes/verification.js'
+);
+const { default: uploadsRoutes } = await import('@/routes/uploads.js');
+const { default: uploadsServeRoutes } = await import(
+  '@/routes/uploads-serve.js'
+);
+const { default: accountsRoutes } = await import('@/routes/accounts.js');
+const { default: statsRoutes } = await import('@/routes/stats.js');
+const { default: metricsRoutes } = await import('@/routes/metrics.js');
+const { default: adminSessionsRoutes } = await import(
+  '@/routes/admin-sessions.js'
+);
+
+metricsService.start();
+
+await app.register(uploadsServeRoutes);
+
+await app.register(
+  async (app) => {
+    await app.register(usersRoutes);
+    await app.register(sessionsRoutes);
+    await app.register(passwordRoutes);
+    await app.register(verificationRoutes);
+    await app.register(uploadsRoutes);
+    await app.register(accountsRoutes);
+    await app.register(statsRoutes);
+    await app.register(metricsRoutes);
+    await app.register(adminSessionsRoutes);
+  },
+  { prefix: '/api' }
+);

package/template/apps/api/src/common/logger.service.ts

@@ -0,0 +1,227 @@
+import type { FastifyBaseLogger } from 'fastify';
+import pino, { type Logger } from 'pino';
+
+import { loadEnv } from '@/config/env';
+
+type VerbosityLevel = 'minimal' | 'normal' | 'detailed' | 'verbose';
+type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+
+interface LogContext {
+  [key: string]: unknown;
+}
+
+interface PerformanceMetrics {
+  operation: string;
+  duration: number;
+  [key: string]: unknown;
+}
+
+export class LoggerService {
+  private readonly logger: Logger | FastifyBaseLogger;
+  private readonly globalVerbosity: VerbosityLevel;
+  private readonly isDevelopment: boolean;
+  private verbosityOverride?: VerbosityLevel;
+  private context?: string;
+
+  constructor(existingLogger?: Logger | FastifyBaseLogger) {
+    const env = loadEnv();
+    this.isDevelopment = env.NODE_ENV === 'development';
+    this.globalVerbosity = env.LOG_LEVEL;
+
+    if (existingLogger) {
+      this.logger = existingLogger;
+    } else {
+      this.logger = pino({
+        level: 'trace',
+        formatters: {
+          level: (label) => ({ level: label }),
+        },
+        serializers: {
+          err: pino.stdSerializers.err,
+          error: pino.stdSerializers.err,
+          req: pino.stdSerializers.req,
+          res: pino.stdSerializers.res,
+        },
+        transport: this.isDevelopment
+          ? {
+              target: 'pino-pretty',
+              options: {
+                colorize: true,
+                ignore: 'pid,hostname',
+                singleLine: false,
+                messageFormat: '{if context}[{context}] {end}{msg}',
+                translateTime: 'HH:MM:ss',
+              },
+            }
+          : undefined,
+      });
+    }
+  }
+
+  minimal(): this {
+    const instance = this.clone();
+    instance.verbosityOverride = 'minimal';
+    return instance;
+  }
+
+  normal(): this {
+    const instance = this.clone();
+    instance.verbosityOverride = 'normal';
+    return instance;
+  }
+
+  detailed(): this {
+    const instance = this.clone();
+    instance.verbosityOverride = 'detailed';
+    return instance;
+  }
+
+  verbose(): this {
+    const instance = this.clone();
+    instance.verbosityOverride = 'verbose';
+    return instance;
+  }
+
+  setContext(context: string): void {
+    this.context = context;
+  }
+
+  child(context: string): LoggerService {
+    const instance = this.clone();
+    instance.context = context;
+    return instance;
+  }
+
+  log(message: string, context?: LogContext): void {
+    this.info(message, context);
+  }
+
+  info(message: string, context?: LogContext): void {
+    if (this.shouldLog('info')) {
+      this.writeLog('info', message, context);
+    }
+  }
+
+  error(message: string, error?: Error | string, context?: LogContext): void {
+    if (this.shouldLog('error')) {
+      const errorContext =
+        error instanceof Error
+          ? { err: error, ...context }
+          : error
+            ? { trace: error, ...context }
+            : context;
+
+      this.writeLog('error', message, errorContext);
+    }
+  }
+
+  warn(message: string, context?: LogContext): void {
+    if (this.shouldLog('warn')) {
+      this.writeLog('warn', message, context);
+    }
+  }
+
+  debug(message: string, context?: LogContext): void {
+    if (this.shouldLog('debug')) {
+      this.writeLog('debug', message, context);
+    }
+  }
+
+  trace(message: string, context?: LogContext): void {
+    if (this.shouldLog('trace')) {
+      this.writeLog('trace', message, context);
+    }
+  }
+
+  perf(message: string, metrics: PerformanceMetrics): void {
+    if (this.shouldLog('debug')) {
+      this.writeLog('debug', message, {
+        performance: true,
+        ...metrics,
+      });
+    }
+  }
+
+  getVerbosity(): VerbosityLevel {
+    return this.verbosityOverride ?? this.globalVerbosity;
+  }
+
+  getRawLogger(): Logger | FastifyBaseLogger {
+    return this.logger;
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    const effectiveVerbosity = this.verbosityOverride ?? this.globalVerbosity;
+
+    const verbosityOrder: VerbosityLevel[] = [
+      'minimal',
+      'normal',
+      'detailed',
+      'verbose',
+    ];
+    const currentLevel =
+      verbosityOrder.indexOf(effectiveVerbosity) >= 0
+        ? verbosityOrder.indexOf(effectiveVerbosity)
+        : 1;
+
+    switch (level) {
+      case 'error':
+      case 'warn':
+        return currentLevel >= 0;
+      case 'info':
+        return currentLevel >= 1;
+      case 'debug':
+        return currentLevel >= 2;
+      case 'trace':
+        return currentLevel >= 3;
+      default:
+        return false;
+    }
+  }
+
+  private writeLog(
+    level: 'info' | 'error' | 'warn' | 'debug' | 'trace',
+    message: string,
+    context?: LogContext
+  ): void {
+    const effectiveVerbosity = this.verbosityOverride ?? this.globalVerbosity;
+    const enrichedContext: LogContext = {};
+
+    if (effectiveVerbosity === 'minimal') {
+      // Minimal: message only + critical error fields
+      if (context?.err) enrichedContext.err = context.err;
+      if (context?.error) enrichedContext.error = context.error;
+    } else if (effectiveVerbosity === 'normal') {
+      // Normal: [context] + message + error fields (no additional fields)
+      if (this.context) {
+        enrichedContext.context = this.context;
+      }
+      if (context?.err) enrichedContext.err = context.err;
+      if (context?.error) enrichedContext.error = context.error;
+      if (context?.trace) enrichedContext.trace = context.trace;
+    } else {
+      // Detailed & Verbose: [context] + message + all fields
+      if (this.context) {
+        enrichedContext.context = this.context;
+      }
+      if (context) {
+        Object.assign(enrichedContext, context);
+      }
+    }
+
+    (this.logger[level] as (obj: object, msg?: string) => void)(
+      enrichedContext,
+      message
+    );
+  }
+
+  private clone(): this {
+    const instance = Object.create(Object.getPrototypeOf(this));
+    instance.logger = this.logger;
+    instance.globalVerbosity = this.globalVerbosity;
+    instance.isDevelopment = this.isDevelopment;
+    instance.context = this.context;
+    instance.verbosityOverride = this.verbosityOverride;
+    return instance;
+  }
+}

package/template/apps/api/src/config/env.ts

@@ -0,0 +1,60 @@
+import dotenvFlow from 'dotenv-flow';
+import { z } from 'zod';
+
+const EnvSchema = z.object({
+  NODE_ENV: z
+    .enum(['development', 'production', 'test'])
+    .default('development'),
+  API_URL: z.string().url(),
+  FRONTEND_URL: z.string().url(),
+  DATABASE_URL: z.string().min(1),
+  PORT: z.string().transform(Number).pipe(z.number().int().positive()),
+  COOKIE_SECRET: z
+    .string()
+    .min(16, 'COOKIE_SECRET must be at least 16 characters'),
+  LOG_LEVEL: z
+    .enum(['minimal', 'normal', 'detailed', 'verbose'])
+    .default('normal'),
+  BETTER_AUTH_SECRET: z
+    .string()
+    .min(32, 'BETTER_AUTH_SECRET must be at least 32 characters'),
+  BETTER_AUTH_URL: z.string().url(),
+
+  // OAuth Provider Credentials (Optional)
+  // Only required if you enable social login providers in Better Auth configuration
+  // Leave empty to use email/password authentication only
+  GITHUB_CLIENT_ID: z.string().optional(),
+  GITHUB_CLIENT_SECRET: z.string().optional(),
+  GOOGLE_CLIENT_ID: z.string().optional(),
+  GOOGLE_CLIENT_SECRET: z.string().optional(),
+
+  // Email Service Configuration (Optional)
+  // If RESEND_API_KEY is not provided, emails will be logged to console (dev mode)
+  // EMAIL_FROM: The sender email address (e.g., 'noreply@yourdomain.com')
+  // Note: You MUST verify your domain in Resend dashboard before sending emails
+  RESEND_API_KEY: z.string().optional(),
+  EMAIL_FROM: z.string().email().optional(),
+
+  // File Storage Configuration (Optional)
+  STORAGE_TYPE: z.enum(['local', 's3', 'r2']).optional().default('local'),
+  S3_BUCKET: z.string().optional(),
+  S3_REGION: z.string().optional(),
+  S3_ACCESS_KEY_ID: z.string().optional(),
+  S3_SECRET_ACCESS_KEY: z.string().optional(),
+  S3_ENDPOINT: z.string().url().optional(), // For R2/MinIO compatibility
+});
+
+export type Env = z.infer<typeof EnvSchema>;
+
+export function loadEnv(path?: string): Env {
+  dotenvFlow.config({ path: path || process.cwd() });
+
+  const result = EnvSchema.safeParse(process.env);
+
+  if (!result.success) {
+    console.error('❌ Invalid environment variables:', result.error.format());
+    throw new Error('Invalid environment variables');
+  }
+
+  return result.data;
+}

package/template/apps/api/src/config/rate-limit.ts

@@ -0,0 +1,29 @@
+export const RATE_LIMIT_CONFIG = {
+  // Role-based rate limits (requests per minute)
+  admin: {
+    max: 200,
+    timeWindow: 60 * 1000,
+  },
+  user: {
+    max: 60,
+    timeWindow: 60 * 1000,
+  },
+  anonymous: {
+    max: 30,
+    timeWindow: 60 * 1000,
+  },
+
+  // Route-specific overrides
+  routes: {
+    auth: {
+      max: 10,
+      timeWindow: 60 * 1000,
+    },
+    uploads: {
+      max: 20,
+      timeWindow: 60 * 1000,
+    },
+  },
+} as const;
+
+export type RateLimitRole = 'admin' | 'user' | 'anonymous';