Contributing Guide¶

// tsconfig.json already enforces strict mode
// Always use explicit types, avoid 'any'

// ❌ Bad
function process(data: any) {
  return data.value;
}

// ✅ Good
function process(data: { value: number }): number {
  return data.value;
}

// ✅ Good
interface User {
  id: number;
  email: string;
}

type UserRole = 'admin' | 'staff' | 'client';
type UserWithRole = User & { role: UserRole };

// Use optional chaining and nullish coalescing
const value = user?.profile?.name ?? 'Unknown';

// Avoid non-null assertions unless absolutely certain
// ❌ Bad: user!.profile!.name
// ✅ Good: Use optional chaining or type guards

import { Controller, Get, Post, Put, Delete, Body, Param, Query } from '@nestjs/common';
import { Auth } from '../auth/decorators/auth.decorator';
import { CurrentUser } from '../auth/decorators/current-user.decorator';
import { User } from '../users/user.entity';

@Controller('products')
@Auth()  // Require authentication for all routes
export class ProductsController {
  constructor(private readonly productsService: ProductsService) {}

  @Get()
  async findAll(@Query() query: ProductQueryDto) {
    return this.productsService.findAll(query);
  }

  @Get(':id')
  async findOne(@Param('id', ParseIntPipe) id: number) {
    return this.productsService.findOne(id);
  }

  @Post()
  @Auth('admin', 'manager')  // Specific roles
  async create(
    @Body() createDto: CreateProductDto,
    @CurrentUser() user: User,
  ) {
    return this.productsService.create(createDto);
  }

  @Put(':id')
  @Auth('admin', 'manager')
  async update(
    @Param('id', ParseIntPipe) id: number,
    @Body() updateDto: UpdateProductDto,
  ) {
    return this.productsService.update(id, updateDto);
  }

  @Delete(':id')
  @Auth('admin')  // Admin only
  async remove(@Param('id', ParseIntPipe) id: number) {
    return this.productsService.remove(id);
  }
}

import { Injectable, NotFoundException } from '@nestjs/common';
import { ProductsRepository } from './products.repository';
import { CreateProductDto, UpdateProductDto, ProductQueryDto } from './dto';
import { Product } from './product.entity';

@Injectable()
export class ProductsService {
  constructor(
    private readonly productsRepository: ProductsRepository,
  ) {}

  async findAll(query: ProductQueryDto): Promise<Product[]> {
    // TenantScopedRepository automatically adds WHERE organizationId = :organizationId
    return this.productsRepository.find({
      where: {
        ...(query.search && { name: Like(`%${query.search}%`) }),
      },
      skip: (query.page - 1) * query.limit,
      take: query.limit,
    });
  }

  async findOne(id: number): Promise<Product> {
    const product = await this.productsRepository.findOne({
      where: { id },
    });

    if (!product) {
      throw new NotFoundException(`Product with ID ${id} not found`);
    }

    return product;
  }

  async create(createDto: CreateProductDto): Promise<Product> {
    const product = this.productsRepository.create(createDto);
    // organizationId is automatically set by TenantContext
    return this.productsRepository.save(product);
  }

  async update(id: number, updateDto: UpdateProductDto): Promise<Product> {
    const product = await this.findOne(id);
    Object.assign(product, updateDto);
    return this.productsRepository.save(product);
  }

  async remove(id: number): Promise<void> {
    const product = await this.findOne(id);
    await this.productsRepository.remove(product);
  }
}

// Server Component (default, RSC)
// ✅ Use for: Data fetching, accessing backend directly, SEO
export default async function ProductsPage() {
  const products = await fetch('http://localhost:3001/api/products').then(r => r.json());

  return (
    <div>
      <h1>Products</h1>
      <ProductList products={products} />
    </div>
  );
}

// Client Component
// ✅ Use for: Interactivity, state, effects, browser APIs
'use client';

import { useState } from 'react';

export function ProductList({ products }) {
  const [filter, setFilter] = useState('');
  // ... interactive logic
}

// hooks/useProducts.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { productsApi } from '@/services/products.service';

export function useProducts(query?: ProductQueryParams) {
  return useQuery({
    queryKey: ['products', query],
    queryFn: () => productsApi.getAll(query),
  });
}

export function useCreateProduct() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: CreateProductDto) => productsApi.create(data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['products'] });
    },
  });
}

// Component usage
'use client';

export function ProductsPage() {
  const { data: products, isLoading } = useProducts();
  const createProduct = useCreateProduct();

  if (isLoading) return <Spinner />;

  return <ProductList products={products} />;
}

// 1. External dependencies
import { Controller, Get, Post } from '@nestjs/common';
import { ApiTags, ApiOperation } from '@nestjs/swagger';

// 2. Internal modules (absolute imports)
import { Auth } from '@/modules/auth/decorators/auth.decorator';
import { User } from '@/modules/users/user.entity';

// 3. Shared packages
import { CreateProductDto } from '@mmr/types';
import { productSchema } from '@mmr/schemas';

// 4. Relative imports
import { ProductsService } from './products.service';
import { Product } from './product.entity';

// ✅ CORRECT: Extends TenantScopedRepository
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { Product } from './product.entity';
import { TenantScopedRepository } from '../../common/repositories/tenant-scoped.repository';

@Injectable()
export class ProductsRepository extends TenantScopedRepository<Product> {
  constructor(
    @InjectRepository(Product)
    private readonly productRepository: Repository<Product>,
  ) {
    super(
      productRepository.target,
      productRepository.manager,
      productRepository.queryRunner,
    );
  }
}

// All queries automatically filtered by organizationId:
// - find(), findOne(), findBy()
// - count(), findAndCount()
// - createTenantQueryBuilder()

// ❌ WRONG: Direct Repository usage (data leak risk!)
@Injectable()
export class ProductsService {
  constructor(
    @InjectRepository(Product)
    private productRepository: Repository<Product>,  // NO!
  ) {}

  async findAll() {
    // This returns products from ALL organizations!
    return this.productRepository.find();  // DANGEROUS!
  }
}

// TenantContext is automatically available in services
import { TenantContext } from '@/common/utils/tenant-context';

async someOperation() {
  const organizationId = TenantContext.getCurrentTenantId();
  const userId = TenantContext.getCurrentUserId();

  // Use for manual queries or logging
  console.log(`User ${userId} from org ${organizationId}`);
}

// products.service.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { ProductsService } from './products.service';
import { ProductsRepository } from './products.repository';
import { Product } from './product.entity';

describe('ProductsService', () => {
  let service: ProductsService;
  let repository: ProductsRepository;

  const mockRepository = {
    find: jest.fn(),
    findOne: jest.fn(),
    create: jest.fn(),
    save: jest.fn(),
    remove: jest.fn(),
  };

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        ProductsService,
        {
          provide: ProductsRepository,
          useValue: mockRepository,
        },
      ],
    }).compile();

    service = module.get<ProductsService>(ProductsService);
    repository = module.get<ProductsRepository>(ProductsRepository);
  });

  afterEach(() => {
    jest.clearAllMocks();
  });

  describe('findAll', () => {
    it('should return array of products', async () => {
      const mockProducts = [{ id: 1, name: 'Product 1' }];
      mockRepository.find.mockResolvedValue(mockProducts);

      const result = await service.findAll({});

      expect(result).toEqual(mockProducts);
      expect(repository.find).toHaveBeenCalled();
    });
  });

  describe('findOne', () => {
    it('should return a product', async () => {
      const mockProduct = { id: 1, name: 'Product 1' };
      mockRepository.findOne.mockResolvedValue(mockProduct);

      const result = await service.findOne(1);

      expect(result).toEqual(mockProduct);
    });

    it('should throw NotFoundException when product not found', async () => {
      mockRepository.findOne.mockResolvedValue(null);

      await expect(service.findOne(999)).rejects.toThrow(NotFoundException);
    });
  });
});

// products.e2e-spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from '../src/app.module';

describe('Products API (e2e)', () => {
  let app: INestApplication;
  let authToken: string;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();

    // Login to get auth token
    const loginResponse = await request(app.getHttpServer())
      .post('/api/auth/login')
      .send({ email: 'admin@example.com', password: 'password' });

    authToken = loginResponse.body.tokens.accessToken;
  });

  afterAll(async () => {
    await app.close();
  });

  describe('GET /api/products', () => {
    it('should return products array', () => {
      return request(app.getHttpServer())
        .get('/api/products')
        .set('Authorization', `Bearer ${authToken}`)
        .expect(200)
        .expect((res) => {
          expect(Array.isArray(res.body.data)).toBe(true);
        });
    });

    it('should return 401 without auth token', () => {
      return request(app.getHttpServer())
        .get('/api/products')
        .expect(401);
    });
  });

  describe('POST /api/products', () => {
    it('should create new product', () => {
      return request(app.getHttpServer())
        .post('/api/products')
        .set('Authorization', `Bearer ${authToken}`)
        .send({
          name: 'New Product',
          price: 99.99,
          sku: 'PROD-001',
        })
        .expect(201)
        .expect((res) => {
          expect(res.body.data).toHaveProperty('id');
          expect(res.body.data.name).toBe('New Product');
        });
    });
  });
});

describe('Tenant Isolation', () => {
  it('should only return products from current organization', async () => {
    // Set tenant context for Org 1
    await TenantContext.run(
      { tenantId: '1', userId: '1', roles: [] },
      async () => {
        const products = await productsRepository.find();

        // All products should belong to Org 1
        expect(products.every(p => p.organizationId === 1)).toBe(true);
      },
    );
  });

  it('should prevent cross-tenant access', async () => {
    // User from Org 1 trying to access Org 2's product
    await TenantContext.run(
      { tenantId: '1', userId: '1', roles: [] },
      async () => {
        // Product 999 belongs to Org 2
        const product = await productsRepository.findOne({ where: { id: 999 } });

        // Should return null (not found in this org)
        expect(product).toBeNull();
      },
    );
  });
});

// 1234567890123-AddProductsTable.ts
import { MigrationInterface, QueryRunner, Table } from 'typeorm';

export class AddProductsTable1234567890123 implements MigrationInterface {
  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.createTable(
      new Table({
        name: 'products',
        columns: [
          {
            name: 'id',
            type: 'int',
            isPrimary: true,
            isGenerated: true,
            generationStrategy: 'increment',
          },
          {
            name: 'name',
            type: 'varchar',
            length: '255',
          },
          {
            name: 'organization_id',
            type: 'int',
          },
          // ... more columns
        ],
      }),
    );
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.dropTable('products');
  }
}

// apps/web/src/services/products.service.ts
import { apiClient } from '@mmr/api-client';
import type { Product, CreateProductDto, ProductQueryParams } from '@mmr/types';

export const productsApi = {
  async getAll(params?: ProductQueryParams): Promise<Product[]> {
    const { data } = await apiClient.get('/products', { params });
    return data.data;
  },

  async getOne(id: number): Promise<Product> {
    const { data } = await apiClient.get(`/products/${id}`);
    return data.data;
  },

  async create(dto: CreateProductDto): Promise<Product> {
    const { data } = await apiClient.post('/products', dto);
    return data.data;
  },

  async update(id: number, dto: Partial<CreateProductDto>): Promise<Product> {
    const { data } = await apiClient.put(`/products/${id}`, dto);
    return data.data;
  },

  async delete(id: number): Promise<void> {
    await apiClient.delete(`/products/${id}`);
  },
};