create-blitzpack 0.1.0

package/template/apps/api/src/services/users.service.spec.ts

@@ -0,0 +1,249 @@
+import { createMockAuthorizationService } from '@test/helpers/mock-authorization';
+import { createMockLogger } from '@test/helpers/mock-logger';
+import { createMockPrisma } from '@test/helpers/mock-prisma';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { LoggerService } from '@/common/logger.service';
+import type { PrismaClient } from '@/generated/client/client.js';
+import type { AuthorizationService } from '@/services/authorization.service';
+
+import { UsersService } from './users.service';
+
+describe('UsersService', () => {
+  let service: UsersService;
+  let prisma: PrismaClient;
+  let logger: LoggerService;
+  let authorizationService: AuthorizationService;
+
+  beforeEach(() => {
+    logger = createMockLogger();
+    prisma = createMockPrisma();
+    authorizationService = createMockAuthorizationService();
+    service = new UsersService(prisma, logger, authorizationService);
+  });
+
+  describe('getUsers', () => {
+    const defaultQuery = {
+      page: 1,
+      limit: 10,
+      sortBy: 'createdAt' as const,
+      sortOrder: 'desc' as const,
+    };
+
+    const mockUsers = [
+      {
+        id: '1',
+        email: 'user1@test.com',
+        name: 'User 1',
+        emailVerified: false,
+        image: null,
+        role: 'user' as const,
+        banned: false,
+        banReason: null,
+        banExpires: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+      {
+        id: '2',
+        email: 'user2@test.com',
+        name: 'User 2',
+        emailVerified: false,
+        image: null,
+        role: 'user' as const,
+        banned: false,
+        banReason: null,
+        banExpires: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    ];
+
+    it('should return empty paginated response initially', async () => {
+      vi.mocked(prisma.user.findMany).mockResolvedValue([]);
+      vi.mocked(prisma.user.count).mockResolvedValue(0);
+
+      const result = await service.getUsers(defaultQuery);
+      expect(result.data).toEqual([]);
+      expect(result.pagination.total).toBe(0);
+      expect(result.pagination.totalPages).toBe(0);
+    });
+
+    it('should return paginated users', async () => {
+      vi.mocked(prisma.user.findMany).mockResolvedValue(mockUsers);
+      vi.mocked(prisma.user.count).mockResolvedValue(2);
+
+      const result = await service.getUsers(defaultQuery);
+      expect(result.data).toHaveLength(2);
+      expect(result.pagination.total).toBe(2);
+      expect(result.pagination.totalPages).toBe(1);
+    });
+
+    it('should handle pagination correctly', async () => {
+      vi.mocked(prisma.user.findMany).mockResolvedValue([mockUsers[0]]);
+      vi.mocked(prisma.user.count).mockResolvedValue(3);
+
+      const result = await service.getUsers({
+        ...defaultQuery,
+        page: 1,
+        limit: 2,
+      });
+      expect(result.data).toHaveLength(1);
+      expect(result.pagination.total).toBe(3);
+      expect(result.pagination.totalPages).toBe(2);
+    });
+
+    it('should filter users by search query', async () => {
+      vi.mocked(prisma.user.findMany).mockResolvedValue([mockUsers[0]]);
+      vi.mocked(prisma.user.count).mockResolvedValue(1);
+
+      const result = await service.getUsers({
+        ...defaultQuery,
+        search: 'user1',
+      });
+      expect(result.data).toHaveLength(1);
+      expect(result.data[0].email).toBe('user1@test.com');
+    });
+  });
+
+  describe('getUserById', () => {
+    const mockUser = {
+      id: '1',
+      email: 'test@example.com',
+      name: 'Test User',
+      emailVerified: false,
+      image: null,
+      role: 'user' as const,
+      banned: false,
+      banReason: null,
+      banExpires: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    it('should return user by ID', async () => {
+      vi.mocked(prisma.user.findUnique).mockResolvedValue(mockUser);
+
+      const user = await service.getUserById('1');
+
+      expect(user).toEqual(mockUser);
+      expect(user?.id).toBe('1');
+    });
+
+    it('should throw NotFoundError when user not found', async () => {
+      vi.mocked(prisma.user.findUnique).mockResolvedValue(null);
+
+      await expect(service.getUserById('non-existent-id')).rejects.toThrow(
+        'User not found'
+      );
+    });
+  });
+
+  describe('createUser', () => {
+    const mockUser = {
+      id: '1',
+      email: 'test@example.com',
+      name: 'Test User',
+      emailVerified: false,
+      image: null,
+      role: 'user' as const,
+      banned: false,
+      banReason: null,
+      banExpires: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    it('should create a new user', async () => {
+      vi.mocked(prisma.user.create).mockResolvedValue(mockUser);
+
+      const user = await service.createUser({
+        email: 'test@example.com',
+        name: 'Test User',
+        role: 'user',
+      });
+
+      expect(user.id).toBe('1');
+      expect(user.email).toBe('test@example.com');
+      expect(user.name).toBe('Test User');
+    });
+  });
+
+  describe('updateUser', () => {
+    const mockUser = {
+      id: '1',
+      email: 'test@example.com',
+      name: 'Test User',
+      emailVerified: false,
+      image: null,
+      role: 'user' as const,
+      banned: false,
+      banReason: null,
+      banExpires: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    const updatedUser = {
+      ...mockUser,
+      name: 'Updated Name',
+    };
+
+    it('should update user successfully', async () => {
+      vi.mocked(prisma.user.findUnique).mockResolvedValue(mockUser);
+      vi.mocked(prisma.user.update).mockResolvedValue(updatedUser);
+
+      const user = await service.updateUser('actor-id', 'super_admin', '1', {
+        name: 'Updated Name',
+      });
+
+      expect(user?.name).toBe('Updated Name');
+      expect(user?.id).toBe('1');
+    });
+
+    it('should throw NotFoundError when user not found', async () => {
+      vi.mocked(prisma.user.findUnique).mockResolvedValue(null);
+
+      await expect(
+        service.updateUser('actor-id', 'super_admin', 'non-existent-id', {
+          name: 'New Name',
+        })
+      ).rejects.toThrow('User not found');
+    });
+  });
+
+  describe('deleteUser', () => {
+    const mockUser = {
+      id: '1',
+      email: 'test@example.com',
+      name: 'Test User',
+      emailVerified: false,
+      image: null,
+      role: 'user' as const,
+      banned: false,
+      banReason: null,
+      banExpires: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    it('should delete user successfully', async () => {
+      vi.mocked(prisma.user.findUnique).mockResolvedValue(mockUser);
+      vi.mocked(prisma.user.delete).mockResolvedValue(mockUser);
+
+      await service.deleteUser('actor-id', 'super_admin', '1');
+
+      expect(prisma.user.delete).toHaveBeenCalledWith({
+        where: { id: '1' },
+      });
+    });
+
+    it('should throw NotFoundError when user not found', async () => {
+      vi.mocked(prisma.user.findUnique).mockResolvedValue(null);
+
+      await expect(
+        service.deleteUser('actor-id', 'super_admin', 'non-existent-id')
+      ).rejects.toThrow('User not found');
+    });
+  });
+});

package/template/apps/api/src/services/users.service.ts

@@ -0,0 +1,198 @@
+import {
+  type PaginatedResponse,
+  type QueryUsers,
+} from '@repo/packages-types/pagination';
+import { type Role } from '@repo/packages-types/role';
+import {
+  type CreateUser,
+  type UpdateUser,
+  type User,
+} from '@repo/packages-types/user';
+import { ForbiddenError, NotFoundError } from '@repo/packages-utils/errors';
+
+import type { LoggerService } from '@/common/logger.service';
+import type { PrismaClient } from '@/generated/client/client.js';
+import type { AuthorizationService } from '@/services/authorization.service';
+
+export class UsersService {
+  constructor(
+    private readonly prisma: PrismaClient,
+    private readonly logger: LoggerService,
+    private readonly authorizationService: AuthorizationService
+  ) {
+    this.logger.setContext('UsersService');
+  }
+
+  async getUsers(query: QueryUsers): Promise<PaginatedResponse<User>> {
+    const where = query.search
+      ? {
+          OR: [
+            { name: { contains: query.search, mode: 'insensitive' as const } },
+            { email: { contains: query.search, mode: 'insensitive' as const } },
+          ],
+        }
+      : undefined;
+
+    const [users, total] = await Promise.all([
+      this.prisma.user.findMany({
+        where,
+        orderBy: { [query.sortBy]: query.sortOrder },
+        skip: (query.page - 1) * query.limit,
+        take: query.limit,
+      }),
+      this.prisma.user.count({ where }),
+    ]);
+
+    const totalPages = Math.ceil(total / query.limit);
+
+    return {
+      data: users as User[],
+      pagination: {
+        page: query.page,
+        limit: query.limit,
+        total,
+        totalPages,
+      },
+    };
+  }
+
+  async getUserById(id: string): Promise<User> {
+    const user = await this.prisma.user.findUnique({
+      where: { id },
+    });
+
+    if (!user) {
+      this.logger.warn('User not found', { userId: id });
+      throw new NotFoundError('User not found', { userId: id });
+    }
+
+    return user as User;
+  }
+
+  async createUser(createUser: CreateUser): Promise<User> {
+    this.logger.info('Creating user', { email: createUser.email });
+
+    const user = await this.prisma.user.create({
+      data: {
+        email: createUser.email,
+        name: createUser.name,
+      },
+    });
+
+    this.logger.info('User created successfully', { userId: user.id });
+    return user as User;
+  }
+
+  async updateUser(
+    actorId: string,
+    actorRole: Role,
+    targetId: string,
+    updateUser: UpdateUser
+  ): Promise<User> {
+    this.logger.info('Updating user', {
+      actorId,
+      actorRole,
+      targetId,
+    });
+
+    const targetUser = await this.prisma.user.findUnique({
+      where: { id: targetId },
+    });
+
+    if (!targetUser) {
+      this.logger.warn('User not found for update', { userId: targetId });
+      throw new NotFoundError('User not found', { userId: targetId });
+    }
+
+    // Check if actor can modify target user
+    this.authorizationService.assertCanModifyUser(
+      actorId,
+      actorRole,
+      targetId,
+      targetUser.role as Role
+    );
+
+    // Check role change permissions
+    if (updateUser.role && updateUser.role !== targetUser.role) {
+      this.authorizationService.assertCanChangeRole(
+        actorId,
+        actorRole,
+        targetId,
+        targetUser.role as Role,
+        updateUser.role
+      );
+    }
+
+    // Check email change permissions
+    if (updateUser.email && updateUser.email !== targetUser.email) {
+      this.authorizationService.assertCanChangeEmail(actorRole);
+    }
+
+    const updatedUser = await this.prisma.user.update({
+      where: { id: targetId },
+      data: updateUser,
+    });
+
+    this.logger.info('User updated successfully', {
+      actorId,
+      targetId,
+      changes: Object.keys(updateUser),
+    });
+    return updatedUser as User;
+  }
+
+  async deleteUser(
+    actorId: string,
+    actorRole: Role,
+    targetId: string
+  ): Promise<void> {
+    this.logger.info('Deleting user', {
+      actorId,
+      actorRole,
+      targetId,
+    });
+
+    const targetUser = await this.prisma.user.findUnique({
+      where: { id: targetId },
+    });
+
+    if (!targetUser) {
+      this.logger.warn('User not found for deletion', { userId: targetId });
+      throw new NotFoundError('User not found', { userId: targetId });
+    }
+
+    // Check if actor can delete target user (includes self-deletion check)
+    this.authorizationService.assertCanDeleteUser(
+      actorId,
+      actorRole,
+      targetId,
+      targetUser.role as Role
+    );
+
+    // Prevent deleting the last super_admin
+    if (targetUser.role === 'super_admin') {
+      const superAdminCount = await this.prisma.user.count({
+        where: { role: 'super_admin' },
+      });
+
+      if (superAdminCount <= 1) {
+        this.logger.warn('Attempt to delete last super admin', {
+          actorId,
+          targetId,
+        });
+        throw new ForbiddenError(
+          'Cannot delete the last super admin. Please promote another user to super admin first.'
+        );
+      }
+    }
+
+    await this.prisma.user.delete({
+      where: { id: targetId },
+    });
+
+    this.logger.info('User deleted successfully', {
+      actorId,
+      targetId,
+    });
+  }
+}

package/template/apps/api/src/utils/file-validation.ts

@@ -0,0 +1,108 @@
+import type { MultipartFile } from '@fastify/multipart';
+
+export const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB in bytes
+
+export const ALLOWED_MIME_TYPES = {
+  // Images
+  'image/jpeg': ['.jpg', '.jpeg'],
+  'image/png': ['.png'],
+  'image/gif': ['.gif'],
+  'image/webp': ['.webp'],
+  'image/svg+xml': ['.svg'],
+  // Documents
+  'application/pdf': ['.pdf'],
+  'application/msword': ['.doc'],
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': [
+    '.docx',
+  ],
+  'application/vnd.ms-excel': ['.xls'],
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': [
+    '.xlsx',
+  ],
+  'text/plain': ['.txt'],
+  'text/csv': ['.csv'],
+} as const;
+
+export type AllowedMimeType = keyof typeof ALLOWED_MIME_TYPES;
+
+export interface FileValidationError {
+  field: string;
+  message: string;
+}
+
+export interface FileValidationResult {
+  valid: boolean;
+  error?: FileValidationError;
+}
+
+export function validateFile(file: MultipartFile): FileValidationResult {
+  const { mimetype, filename } = file;
+
+  // Check if MIME type is allowed
+  if (!isAllowedMimeType(mimetype)) {
+    return {
+      valid: false,
+      error: {
+        field: 'file',
+        message: `File type '${mimetype}' is not allowed. Allowed types: images (JPEG, PNG, GIF, WebP, SVG), documents (PDF, DOC, DOCX, XLS, XLSX, TXT, CSV)`,
+      },
+    };
+  }
+
+  // Validate file extension matches MIME type
+  const extension = getFileExtension(filename);
+  const allowedExtensions = ALLOWED_MIME_TYPES[mimetype as AllowedMimeType];
+
+  if (!(allowedExtensions as readonly string[]).includes(extension)) {
+    return {
+      valid: false,
+      error: {
+        field: 'file',
+        message: `File extension '${extension}' does not match MIME type '${mimetype}'`,
+      },
+    };
+  }
+
+  return { valid: true };
+}
+
+export async function validateFileSize(
+  file: MultipartFile
+): Promise<FileValidationResult> {
+  // Note: @fastify/multipart doesn't provide file size directly
+  // We need to check size during streaming or after buffering
+  // This is handled in the upload handler
+  return { valid: true };
+}
+
+export function isAllowedMimeType(mimetype: string): boolean {
+  return mimetype in ALLOWED_MIME_TYPES;
+}
+
+export function getFileExtension(filename: string): string {
+  const lastDot = filename.lastIndexOf('.');
+  return lastDot === -1 ? '' : filename.slice(lastDot).toLowerCase();
+}
+
+export function isImageFile(mimetype: string): boolean {
+  return mimetype.startsWith('image/');
+}
+
+export function sanitizeFilename(filename: string): string {
+  // Remove path separators and special characters
+  return filename
+    .replace(/[/\\]/g, '')
+    .replace(/[^a-zA-Z0-9._-]/g, '_')
+    .slice(0, 255); // Limit filename length
+}
+
+export function generateUniqueFilename(originalFilename: string): string {
+  const extension = getFileExtension(originalFilename);
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(2, 10);
+  const sanitized = sanitizeFilename(
+    originalFilename.replace(extension, '')
+  ).slice(0, 50);
+
+  return `${timestamp}-${random}-${sanitized}${extension}`;
+}

package/template/apps/api/start.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+set -e
+
+echo "🚀 Starting API deployment..."
+
+# Wait for database to be ready (handles Railway sleep mode)
+echo "⏳ Waiting for database to wake up..."
+
+max_attempts=30
+attempt=0
+
+until npx prisma db push --accept-data-loss --skip-generate || [ $attempt -eq $max_attempts ]; do
+  attempt=$((attempt + 1))
+  echo "   Database not ready yet (attempt $attempt/$max_attempts). Retrying in 2 seconds..."
+  sleep 2
+done
+
+if [ $attempt -eq $max_attempts ]; then
+  echo "❌ Database connection failed after $max_attempts attempts"
+  exit 1
+fi
+
+echo "✅ Database is ready!"
+
+# Run migrations (production-safe, no prompts)
+echo "🔄 Running database migrations..."
+npx prisma migrate deploy
+
+echo "✅ Migrations complete!"
+
+# Start the API server
+echo "🎯 Starting API server..."
+exec node dist/src/main.js

package/template/apps/api/test/helpers/fastify-app.ts

@@ -0,0 +1,24 @@
+import type { FastifyInstance } from 'fastify';
+import Fastify from 'fastify';
+
+import { loadEnv } from '@/config/env';
+
+/**
+ * Create a Fastify test instance with minimal plugins for testing
+ */
+export async function createTestApp(): Promise<FastifyInstance> {
+  loadEnv(); // Load test environment variables
+
+  const app = Fastify({
+    logger: false, // Disable logging in tests
+  });
+
+  return app;
+}
+
+/**
+ * Close the Fastify test instance
+ */
+export async function closeTestApp(app: FastifyInstance): Promise<void> {
+  await app.close();
+}

package/template/apps/api/test/helpers/mock-authorization.ts

@@ -0,0 +1,16 @@
+import { vi } from 'vitest';
+
+import type { AuthorizationService } from '@/services/authorization.service';
+
+export function createMockAuthorizationService(): AuthorizationService {
+  return {
+    canModifyUser: vi.fn().mockReturnValue(true),
+    canDeleteUser: vi.fn().mockReturnValue(true),
+    canChangeRole: vi.fn().mockReturnValue(true),
+    canChangeEmail: vi.fn().mockReturnValue(true),
+    assertCanModifyUser: vi.fn(),
+    assertCanDeleteUser: vi.fn(),
+    assertCanChangeRole: vi.fn(),
+    assertCanChangeEmail: vi.fn(),
+  } as unknown as AuthorizationService;
+}

package/template/apps/api/test/helpers/mock-logger.ts

@@ -0,0 +1,28 @@
+import { vi } from 'vitest';
+
+import type { LoggerService } from '@/common/logger.service';
+
+export function createMockLogger(): LoggerService {
+  const mockLogger = {
+    setContext: vi.fn(),
+    info: vi.fn(),
+    error: vi.fn(),
+    warn: vi.fn(),
+    debug: vi.fn(),
+    http: vi.fn(),
+    child: vi.fn(),
+    minimal: vi.fn(),
+    normal: vi.fn(),
+    detailed: vi.fn(),
+    verbose: vi.fn(),
+  } as unknown as LoggerService;
+
+  // Make verbosity methods chainable
+  mockLogger.minimal = vi.fn().mockReturnValue(mockLogger);
+  mockLogger.normal = vi.fn().mockReturnValue(mockLogger);
+  mockLogger.detailed = vi.fn().mockReturnValue(mockLogger);
+  mockLogger.verbose = vi.fn().mockReturnValue(mockLogger);
+  mockLogger.child = vi.fn().mockReturnValue(mockLogger);
+
+  return mockLogger;
+}

package/template/apps/api/test/helpers/mock-prisma.ts

@@ -0,0 +1,30 @@
+import { vi } from 'vitest';
+
+import type { PrismaClient } from '@/generated/client/client.js';
+
+export function createMockPrisma(): PrismaClient {
+  return {
+    user: {
+      findMany: vi.fn(),
+      findUnique: vi.fn(),
+      findFirst: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      delete: vi.fn(),
+      count: vi.fn(),
+    },
+    session: {
+      findMany: vi.fn(),
+      findUnique: vi.fn(),
+      findFirst: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      delete: vi.fn(),
+      deleteMany: vi.fn(),
+      count: vi.fn(),
+    },
+    $connect: vi.fn(),
+    $disconnect: vi.fn(),
+    $queryRaw: vi.fn(),
+  } as unknown as PrismaClient;
+}