servcraft 0.1.0

package/src/modules/user/user.routes.ts

@@ -0,0 +1,199 @@
+import type { FastifyInstance } from 'fastify';
+import type { UserController } from './user.controller.js';
+import type { AuthService } from '../auth/auth.service.js';
+import { createAuthMiddleware, createRoleMiddleware } from '../auth/auth.middleware.js';
+import { commonResponses, paginationQuery, idParam } from '../swagger/index.js';
+
+const userTag = 'Users';
+const userResponse = {
+  type: 'object',
+  properties: {
+    success: { type: 'boolean', example: true },
+    data: { type: 'object' },
+  },
+};
+
+export function registerUserRoutes(
+  app: FastifyInstance,
+  controller: UserController,
+  authService: AuthService
+): void {
+  const authenticate = createAuthMiddleware(authService);
+  const isAdmin = createRoleMiddleware(['admin', 'super_admin']);
+  const isModerator = createRoleMiddleware(['moderator', 'admin', 'super_admin']);
+
+  // Profile routes (authenticated users)
+  app.get(
+    '/profile',
+    {
+      preHandler: [authenticate],
+      schema: {
+        tags: [userTag],
+        summary: 'Get current user profile',
+        security: [{ bearerAuth: [] }],
+        response: {
+          200: userResponse,
+          401: commonResponses.unauthorized,
+        },
+      },
+    },
+    controller.getProfile.bind(controller)
+  );
+  app.patch(
+    '/profile',
+    {
+      preHandler: [authenticate],
+      schema: {
+        tags: [userTag],
+        summary: 'Update current user profile',
+        security: [{ bearerAuth: [] }],
+        body: { type: 'object' },
+        response: {
+          200: userResponse,
+          401: commonResponses.unauthorized,
+          400: commonResponses.error,
+        },
+      },
+    },
+    controller.updateProfile.bind(controller)
+  );
+
+  // Admin routes
+  app.get(
+    '/users',
+    {
+      preHandler: [authenticate, isModerator],
+      schema: {
+        tags: [userTag],
+        summary: 'List users',
+        security: [{ bearerAuth: [] }],
+        querystring: {
+          ...paginationQuery,
+          properties: {
+            ...paginationQuery.properties,
+            status: { type: 'string', enum: ['active', 'inactive', 'suspended', 'banned'] },
+            role: { type: 'string', enum: ['user', 'admin', 'moderator', 'super_admin'] },
+            search: { type: 'string' },
+            emailVerified: { type: 'boolean' },
+          },
+        },
+        response: {
+          200: commonResponses.paginated,
+          401: commonResponses.unauthorized,
+        },
+      },
+    },
+    controller.list.bind(controller)
+  );
+  app.get(
+    '/users/:id',
+    {
+      preHandler: [authenticate, isModerator],
+      schema: {
+        tags: [userTag],
+        summary: 'Get user by id',
+        security: [{ bearerAuth: [] }],
+        params: idParam,
+        response: {
+          200: userResponse,
+          401: commonResponses.unauthorized,
+          404: commonResponses.notFound,
+        },
+      },
+    },
+    controller.getById.bind(controller)
+  );
+  app.patch(
+    '/users/:id',
+    {
+      preHandler: [authenticate, isAdmin],
+      schema: {
+        tags: [userTag],
+        summary: 'Update user',
+        security: [{ bearerAuth: [] }],
+        params: idParam,
+        body: { type: 'object' },
+        response: {
+          200: userResponse,
+          401: commonResponses.unauthorized,
+          404: commonResponses.notFound,
+        },
+      },
+    },
+    controller.update.bind(controller)
+  );
+  app.delete(
+    '/users/:id',
+    {
+      preHandler: [authenticate, isAdmin],
+      schema: {
+        tags: [userTag],
+        summary: 'Delete user',
+        security: [{ bearerAuth: [] }],
+        params: idParam,
+        response: {
+          204: { description: 'User deleted' },
+          401: commonResponses.unauthorized,
+          404: commonResponses.notFound,
+        },
+      },
+    },
+    controller.delete.bind(controller)
+  );
+
+  // User status management
+  app.post(
+    '/users/:id/suspend',
+    {
+      preHandler: [authenticate, isAdmin],
+      schema: {
+        tags: [userTag],
+        summary: 'Suspend user',
+        security: [{ bearerAuth: [] }],
+        params: idParam,
+        response: {
+          200: userResponse,
+          401: commonResponses.unauthorized,
+          404: commonResponses.notFound,
+        },
+      },
+    },
+    controller.suspend.bind(controller)
+  );
+  app.post(
+    '/users/:id/ban',
+    {
+      preHandler: [authenticate, isAdmin],
+      schema: {
+        tags: [userTag],
+        summary: 'Ban user',
+        security: [{ bearerAuth: [] }],
+        params: idParam,
+        response: {
+          200: userResponse,
+          401: commonResponses.unauthorized,
+          404: commonResponses.notFound,
+        },
+      },
+    },
+    controller.ban.bind(controller)
+  );
+  app.post(
+    '/users/:id/activate',
+    {
+      preHandler: [authenticate, isAdmin],
+      schema: {
+        tags: [userTag],
+        summary: 'Activate user',
+        security: [{ bearerAuth: [] }],
+        params: idParam,
+        response: {
+          200: userResponse,
+          401: commonResponses.unauthorized,
+          404: commonResponses.notFound,
+        },
+      },
+    },
+    controller.activate.bind(controller)
+  );
+}

package/src/modules/user/user.service.ts

@@ -0,0 +1,145 @@
+import type { PaginatedResult, PaginationParams } from '../../types/index.js';
+import { NotFoundError, ConflictError } from '../../utils/errors.js';
+import { UserRepository, createUserRepository } from './user.repository.js';
+import type { User, CreateUserData, UpdateUserData, UserFilters, UserRole } from './types.js';
+import { DEFAULT_ROLE_PERMISSIONS } from './types.js';
+import { logger } from '../../core/logger.js';
+
+export class UserService {
+  constructor(private repository: UserRepository) {}
+
+  async findById(id: string): Promise<User | null> {
+    return this.repository.findById(id);
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.repository.findByEmail(email);
+  }
+
+  async findMany(
+    params: PaginationParams,
+    filters?: UserFilters
+  ): Promise<PaginatedResult<Omit<User, 'password'>>> {
+    const result = await this.repository.findMany(params, filters);
+
+    // Remove passwords from results
+    return {
+      ...result,
+      data: result.data.map(({ password, ...user }) => user) as Omit<User, 'password'>[],
+    };
+  }
+
+  async create(data: CreateUserData): Promise<User> {
+    // Check for existing user
+    const existing = await this.repository.findByEmail(data.email);
+    if (existing) {
+      throw new ConflictError('User with this email already exists');
+    }
+
+    const user = await this.repository.create(data);
+    logger.info({ userId: user.id, email: user.email }, 'User created');
+    return user;
+  }
+
+  async update(id: string, data: UpdateUserData): Promise<User> {
+    const user = await this.repository.findById(id);
+    if (!user) {
+      throw new NotFoundError('User');
+    }
+
+    // Check email uniqueness if changing email
+    if (data.email && data.email !== user.email) {
+      const existing = await this.repository.findByEmail(data.email);
+      if (existing) {
+        throw new ConflictError('Email already in use');
+      }
+    }
+
+    const updatedUser = await this.repository.update(id, data);
+    if (!updatedUser) {
+      throw new NotFoundError('User');
+    }
+
+    logger.info({ userId: id }, 'User updated');
+    return updatedUser;
+  }
+
+  async updatePassword(id: string, hashedPassword: string): Promise<User> {
+    const user = await this.repository.updatePassword(id, hashedPassword);
+    if (!user) {
+      throw new NotFoundError('User');
+    }
+    logger.info({ userId: id }, 'User password updated');
+    return user;
+  }
+
+  async updateLastLogin(id: string): Promise<User> {
+    const user = await this.repository.updateLastLogin(id);
+    if (!user) {
+      throw new NotFoundError('User');
+    }
+    return user;
+  }
+
+  async delete(id: string): Promise<void> {
+    const user = await this.repository.findById(id);
+    if (!user) {
+      throw new NotFoundError('User');
+    }
+
+    await this.repository.delete(id);
+    logger.info({ userId: id }, 'User deleted');
+  }
+
+  async suspend(id: string): Promise<User> {
+    return this.update(id, { status: 'suspended' });
+  }
+
+  async ban(id: string): Promise<User> {
+    return this.update(id, { status: 'banned' });
+  }
+
+  async activate(id: string): Promise<User> {
+    return this.update(id, { status: 'active' });
+  }
+
+  async verifyEmail(id: string): Promise<User> {
+    return this.update(id, { emailVerified: true });
+  }
+
+  async changeRole(id: string, role: UserRole): Promise<User> {
+    return this.update(id, { role });
+  }
+
+  // RBAC helpers
+  hasPermission(role: UserRole, permission: string): boolean {
+    const permissions = DEFAULT_ROLE_PERMISSIONS[role] || [];
+
+    // Super admin has all permissions
+    if (permissions.includes('*:manage')) {
+      return true;
+    }
+
+    // Check exact match
+    if (permissions.includes(permission)) {
+      return true;
+    }
+
+    // Check wildcard match (e.g., "content:manage" matches "content:read")
+    const [resource, action] = permission.split(':');
+    const managePermission = `${resource}:manage`;
+    if (permissions.includes(managePermission)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  getPermissions(role: UserRole): string[] {
+    return DEFAULT_ROLE_PERMISSIONS[role] || [];
+  }
+}
+
+export function createUserService(repository?: UserRepository): UserService {
+  return new UserService(repository || createUserRepository());
+}

package/src/modules/validation/index.ts

@@ -0,0 +1,18 @@
+export {
+  validate,
+  validateBody,
+  validateQuery,
+  validateParams,
+  idParamSchema,
+  paginationSchema,
+  searchSchema,
+  emailSchema,
+  passwordSchema,
+  urlSchema,
+  phoneSchema,
+  dateSchema,
+  futureDateSchema,
+  pastDateSchema,
+} from './validator.js';
+
+export type { IdParam, PaginationInput } from './validator.js';

package/src/modules/validation/validator.ts

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import type { ZodError, ZodTypeAny } from 'zod';
+import { ValidationError } from '../../utils/errors.js';
+
+export function validateBody<T extends ZodTypeAny>(schema: T, data: unknown): z.infer<T> {
+  const result = schema.safeParse(data);
+
+  if (!result.success) {
+    throw new ValidationError(formatZodErrors(result.error));
+  }
+
+  return result.data;
+}
+
+export function validateQuery<T extends ZodTypeAny>(schema: T, data: unknown): z.infer<T> {
+  const result = schema.safeParse(data);
+
+  if (!result.success) {
+    throw new ValidationError(formatZodErrors(result.error));
+  }
+
+  return result.data;
+}
+
+export function validateParams<T extends ZodTypeAny>(schema: T, data: unknown): z.infer<T> {
+  const result = schema.safeParse(data);
+
+  if (!result.success) {
+    throw new ValidationError(formatZodErrors(result.error));
+  }
+
+  return result.data;
+}
+
+export function validate<T extends ZodTypeAny>(schema: T, data: unknown): z.infer<T> {
+  return validateBody(schema, data);
+}
+
+function formatZodErrors(error: ZodError): Record<string, string[]> {
+  const errors: Record<string, string[]> = {};
+
+  for (const issue of error.issues) {
+    const path = issue.path.join('.') || 'root';
+    if (!errors[path]) {
+      errors[path] = [];
+    }
+    errors[path].push(issue.message);
+  }
+
+  return errors;
+}
+
+// Common validation schemas
+export const idParamSchema = z.object({
+  id: z.string().uuid('Invalid ID format'),
+});
+
+export const paginationSchema = z.object({
+  page: z.string().transform(Number).optional().default('1'),
+  limit: z.string().transform(Number).optional().default('20'),
+  sortBy: z.string().optional(),
+  sortOrder: z.enum(['asc', 'desc']).optional().default('asc'),
+});
+
+export const searchSchema = z.object({
+  q: z.string().min(1, 'Search query is required').optional(),
+  search: z.string().min(1).optional(),
+});
+
+// Email validation
+export const emailSchema = z.string().email('Invalid email address');
+
+// Password validation with strength requirements
+export const passwordSchema = z
+  .string()
+  .min(8, 'Password must be at least 8 characters')
+  .regex(/[A-Z]/, 'Password must contain at least one uppercase letter')
+  .regex(/[a-z]/, 'Password must contain at least one lowercase letter')
+  .regex(/[0-9]/, 'Password must contain at least one number')
+  .regex(/[^A-Za-z0-9]/, 'Password must contain at least one special character');
+
+// URL validation
+export const urlSchema = z.string().url('Invalid URL format');
+
+// Phone validation (basic international format)
+export const phoneSchema = z.string().regex(
+  /^\+?[1-9]\d{1,14}$/,
+  'Invalid phone number format'
+);
+
+// Date validation
+export const dateSchema = z.coerce.date();
+export const futureDateSchema = z.coerce.date().refine(
+  (date) => date > new Date(),
+  'Date must be in the future'
+);
+export const pastDateSchema = z.coerce.date().refine(
+  (date) => date < new Date(),
+  'Date must be in the past'
+);
+
+// Type exports
+export type IdParam = z.infer<typeof idParamSchema>;
+export type PaginationInput = z.infer<typeof paginationSchema>;

package/src/types/common.ts

@@ -0,0 +1,61 @@
+import type { FastifyRequest, FastifyReply } from 'fastify';
+
+// Base entity with common fields
+export interface BaseEntity {
+  id: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// Pagination
+export interface PaginationParams {
+  page: number;
+  limit: number;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+export interface PaginatedResult<T> {
+  data: T[];
+  meta: {
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+  };
+}
+
+// API Response
+export interface ApiResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  message?: string;
+  errors?: Record<string, string[]>;
+}
+
+// Service Result
+export type ServiceResult<T, E = Error> =
+  | { success: true; data: T }
+  | { success: false; error: E; message: string };
+
+// Repository interface
+export interface Repository<T extends BaseEntity> {
+  findById(id: string): Promise<T | null>;
+  findMany(params?: PaginationParams): Promise<PaginatedResult<T>>;
+  create(data: Omit<T, keyof BaseEntity>): Promise<T>;
+  update(id: string, data: Partial<Omit<T, keyof BaseEntity>>): Promise<T | null>;
+  delete(id: string): Promise<boolean>;
+}
+
+// Controller handler type
+export type ControllerHandler = (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+
+// Module interface
+export interface Module {
+  name: string;
+  register(app: FastifyInstance): Promise<void>;
+}
+
+import type { FastifyInstance } from 'fastify';

package/src/types/index.ts

@@ -0,0 +1,10 @@
+export type {
+  BaseEntity,
+  PaginationParams,
+  PaginatedResult,
+  ApiResponse,
+  ServiceResult,
+  Repository,
+  ControllerHandler,
+  Module,
+} from './common.js';

package/src/utils/errors.ts

@@ -0,0 +1,66 @@
+export class AppError extends Error {
+  public readonly statusCode: number;
+  public readonly isOperational: boolean;
+  public readonly errors?: Record<string, string[]>;
+
+  constructor(
+    message: string,
+    statusCode = 500,
+    isOperational = true,
+    errors?: Record<string, string[]>
+  ) {
+    super(message);
+    this.statusCode = statusCode;
+    this.isOperational = isOperational;
+    this.errors = errors;
+
+    Object.setPrototypeOf(this, AppError.prototype);
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource = 'Resource') {
+    super(`${resource} not found`, 404);
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized') {
+    super(message, 401);
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = 'Forbidden') {
+    super(message, 403);
+  }
+}
+
+export class BadRequestError extends AppError {
+  constructor(message = 'Bad request', errors?: Record<string, string[]>) {
+    super(message, 400, true, errors);
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message = 'Resource already exists') {
+    super(message, 409);
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(errors: Record<string, string[]>) {
+    super('Validation failed', 422, true, errors);
+  }
+}
+
+export class TooManyRequestsError extends AppError {
+  constructor(message = 'Too many requests') {
+    super(message, 429);
+  }
+}
+
+export function isAppError(error: unknown): error is AppError {
+  return error instanceof AppError;
+}

package/src/utils/index.ts

@@ -0,0 +1,33 @@
+export {
+  success,
+  created,
+  noContent,
+  error,
+  notFound,
+  unauthorized,
+  forbidden,
+  badRequest,
+  conflict,
+  internalError,
+} from './response.js';
+
+export {
+  parsePaginationParams,
+  createPaginatedResult,
+  getSkip,
+  DEFAULT_PAGE,
+  DEFAULT_LIMIT,
+  MAX_LIMIT,
+} from './pagination.js';
+
+export {
+  AppError,
+  NotFoundError,
+  UnauthorizedError,
+  ForbiddenError,
+  BadRequestError,
+  ConflictError,
+  ValidationError,
+  TooManyRequestsError,
+  isAppError,
+} from './errors.js';

package/src/utils/pagination.ts

@@ -0,0 +1,38 @@
+import type { PaginationParams, PaginatedResult } from '../types/index.js';
+
+export const DEFAULT_PAGE = 1;
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 100;
+
+export function parsePaginationParams(query: Record<string, unknown>): PaginationParams {
+  const page = Math.max(1, parseInt(String(query.page || DEFAULT_PAGE), 10));
+  const limit = Math.min(MAX_LIMIT, Math.max(1, parseInt(String(query.limit || DEFAULT_LIMIT), 10)));
+  const sortBy = typeof query.sortBy === 'string' ? query.sortBy : undefined;
+  const sortOrder = query.sortOrder === 'desc' ? 'desc' : 'asc';
+
+  return { page, limit, sortBy, sortOrder };
+}
+
+export function createPaginatedResult<T>(
+  data: T[],
+  total: number,
+  params: PaginationParams
+): PaginatedResult<T> {
+  const totalPages = Math.ceil(total / params.limit);
+
+  return {
+    data,
+    meta: {
+      total,
+      page: params.page,
+      limit: params.limit,
+      totalPages,
+      hasNextPage: params.page < totalPages,
+      hasPrevPage: params.page > 1,
+    },
+  };
+}
+
+export function getSkip(params: PaginationParams): number {
+  return (params.page - 1) * params.limit;
+}