api

Cursor Agent Rules for CaseAI Connect - API

NestJS Dependency Injection

Import Type Rule

When NestJS requires runtime access to classes for dependency injection (services, controllers, guards, etc.), you MUST use regular imports, not type-only imports.

Rule: If you get a NestJS DI error about a class being undefined at runtime, it means you used import type instead of import.

Solution:

• Change import type { MyService } from './my.service' to import { MyService } from './my.service'
• Add a biome-ignore comment: // biome-ignore lint/style/useImportType: Required at runtime for NestJS DI

When to use:

• Services, custom repositories and TransactionService injected through the constructor or @Inject()
• Controllers, Guards, Interceptors, Pipes
• Any class that needs to be available at runtime for NestJS DI

When type-only imports are OK:

• DTOs, interfaces, types
• Return types, parameter types
• Anything not used for DI

Example:

// ❌ Wrong - will cause DI error
import type { UsersService } from "@/users/users.service"

// ✅ Correct
// biome-ignore lint/style/useImportType: Required at runtime for NestJS DI
import { UsersService } from "@/users/users.service"

DTO Organization

Domain-Based DTO Location

Rule: DTOs (Data Transfer Objects) MUST be co-located with their domain logic in packages/api-contracts/src/{domain}/ as a single consolidated file per domain.

Structure:

• All DTOs for a domain MUST be consolidated into a single file: packages/api-contracts/src/{domain}/{domain}.dto.ts (e.g., packages/api-contracts/src/projects/projects.dto.ts, packages/api-contracts/src/me/me.dto.ts)
• DO NOT create separate files for each DTO (e.g., create-project.dto.ts, list-projects.dto.ts, etc.)
• All DTOs are exported from packages/api-contracts/src/index.ts for consumption by both API and frontend
• Controllers and routes import DTOs from @caseai-connect/api-contracts

Why this pattern?

• Reduced file proliferation: Avoids having many small DTO files that are hard to navigate
• Better organization: All related DTOs for a domain are in one place
• Easier maintenance: Related types are easier to find and update together
• Cohesion: DTOs are tightly coupled to domain logic and API contracts
• Single source of truth: DTOs live in a shared package accessible to all consumers
• No circular dependencies: API-contracts is a separate package that API and frontend both depend on
• Frontend integration: Frontend imports directly from @caseai-connect/api-contracts