---

description: Rules for the NestJS API application (apps/api) globs:

• "apps/api/**/*"
• "packages/api-contracts/**/*" alwaysApply: false

---

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

Import Rules:

• Within API: Controllers and routes import DTOs from @caseai-connect/api-contracts
• For frontend: Frontend imports from @caseai-connect/api-contracts

Example - Creating DTOs:

1. Create consolidated DTO file (packages/api-contracts/src/projects/projects.dto.ts):

// Project entity DTO
export type ProjectDto = {
  id: string
  name: string
  organizationId: string
  createdAt: number
  updatedAt: number
}

// Create project DTOs
export type CreateProjectRequestDto = {
  name: string
  organizationId: string
}

export type CreateProjectResponseDto = {
  id: string
  name: string
  organizationId: string
}

// List projects DTOs
export type ListProjectsResponseDto = {
  projects: ProjectDto[]
}

// Update project DTOs
export type UpdateProjectRequestDto = {
  name: string
}

export type UpdateProjectResponseDto = {
  id: string
  name: string
  organizationId: string
}

2. Export from central index (packages/api-contracts/src/index.ts):

export type {
  CreateProjectRequestDto,
  CreateProjectResponseDto,
  ListProjectsResponseDto,
  ProjectDto,
  UpdateProjectRequestDto,
  UpdateProjectResponseDto,
} from "./projects/projects.dto"

3. Import in routes (packages/api-contracts/src/projects/projects.routes.ts):

import type { CreateProjectRequestDto, CreateProjectResponseDto, ListProjectsResponseDto, UpdateProjectRequestDto, UpdateProjectResponseDto } from "./projects.dto"
import type { RequestPayload, ResponseData } from "../generic"

4. Import in controllers (apps/api/src/projects/projects.controller.ts):

import type { CreateProjectRequestDto } from "@caseai-connect/api-contracts"

Controller Guidelines

Route Definition Strategy

All NestJS controllers MUST use the defineRoute strategy for type-safe route definitions. This ensures consistency and enables type inference across the codebase.

Route key naming (CRUD)

Rule: Standard CRUD keys on *Routes objects MUST use these exact names (same as frontend SPI methods):

| Operation | Route key | HTTP | |-----------|-----------|------| | List collection | getAll | GET | | Get single resource | getOne | GET | | Create | createOne | POST | | Update | updateOne | PATCH | | Delete | deleteOne | DELETE |

Forbidden for CRUD: domain-prefixed keys like listOrganizations, createOrganization, updateProject. Prefer OrganizationsRoutes.getAll / createOne, not listOrganizations / createOrganization.

Non-CRUD / singleton routes may use descriptive keys (getMe, acceptTerms, listPendingMine). When in doubt for resource CRUD, use the table above. Pattern: packages/api-contracts/src/agents/agents.routes.ts, projects/projects.routes.ts.

Step 1: Create a Routes File

Create a *.routes.ts file in your domain directory (e.g., organizations.routes.ts, projects.routes.ts).

For list / get-one / delete:

import type { ResponseData, SuccessResponseDTO } from "../generic"
import { defineRoute } from "../helpers"
import type { MyDto } from "./my.dto"

export const MyRoutes = {
  getAll: defineRoute<ResponseData<MyDto[]>>({
    method: "get",
    path: "my/path", // No leading slash - it gets normalized automatically
  }),
  getOne: defineRoute<ResponseData<MyDto>>({
    method: "get",
    path: "my/path/:myId",
  }),
  deleteOne: defineRoute<ResponseData<SuccessResponseDTO>>({
    method: "delete",
    path: "my/path/:myId",
  }),
}

For create / update:

import type { RequestPayload, ResponseData, SuccessResponseDTO } from "../generic"
import { defineRoute } from "../helpers"
import type { MyDto, UpdateMyRequestDto } from "./my.dto"

export const MyRoutes = {
  createOne: defineRoute<ResponseData<MyDto>, RequestPayload<Pick<MyDto, "name">>>({
    method: "post",
    path: "my/path",
  }),
  updateOne: defineRoute<
    ResponseData<SuccessResponseDTO>,
    RequestPayload<UpdateMyRequestDto>
  >({
    method: "patch",
    path: "my/path/:myId",
  }),
}

Important:

• Path should NOT start with / - defineRoute normalizes it automatically
• GET/DELETE routes only need ResponseData<T> type parameter
• POST/PUT/PATCH routes need both ResponseData<TResponse> and RequestPayload<TRequest> type parameters

Step 2: Use Routes in Controller

Import the routes in your controller and use them in decorators:

import { Controller, Get } from "@nestjs/common"
import { MyRoutes } from "./my.routes"

@Controller() // No prefix - paths come from route definitions
export class MyController {
  @Get(MyRoutes.getAll.path) // Use route path directly
  async list(): Promise<typeof MyRoutes.getAll.response> {
    // Always wrap response in { data: ... }
    return {
      data: {
        // ... your response data
      },
    }
  }
}

Controller Rules:

• Use @Controller() with no prefix - paths are defined in routes files
• Use Routes.routeName.path directly in method decorators (@Get, @Post, etc.)
• Use typeof Routes.routeName.response for return type annotation
• Always wrap response objects in { data: ... } to match ResponseData<T> structure
• For POST/PUT/PATCH, request bodies should match RequestPayload<T> (wrapped in { payload: ... })
• Controller method names may be descriptive (listOrganizations); route keys stay getAll / createOne / etc.

Context Resolver Architecture (Required)

Controllers and guards MUST follow the context resolver pattern for resource loading:

• Use ResourceContextGuard to resolve request context (organization, project, projectMembership, agent, etc.)
• Declare required context at controller or method level with @RequireContext(...)
• Add route-specific context with @AddContext(...) when only some handlers need extra resources
• Check access with CheckPermissionGuard after ResourceContextGuard and @CheckPermission(...) on each route (see the RBAC section below). The permission guard loads no resource
• Do not use cascading resource-loading guards like UserGuard -> OrganizationGuard -> ProjectsGuard to populate request resources
• Do not fetch domain resources in a guard when a context resolver exists

Module wiring rules:

• Register ResourceContextGuard in module providers
• Register each resolver used by the module (e.g., OrganizationContextResolver, ProjectContextResolver, ProjectMembershipContextResolver)
• Import RbacModule, which provides CheckPermissionGuard and PermissionService
• Keep JwtAuthGuard and UserGuard for authentication/user hydration; use resolvers for resource hydration

Example pattern:

@UseGuards(JwtAuthGuard, UserGuard, ResourceContextGuard, CheckPermissionGuard)
@RequireContext("organization", "project")
@Controller()
export class ExampleController {
  @Delete("organizations/:organizationId/projects/:projectId/memberships/:membershipId")
  @AddContext("projectMembership")
  @CheckPermission(PROJECT_MEMBER_DELETE_PERMISSION, "project")
  async remove(@Req() request: EndpointRequestWithProjectMembership) {
    return { data: { success: true } }
  }
}

Step 3: Export Routes

Export your routes in packages/api-contracts/src/api-routes/index.ts:

import { MyRoutes } from "../my/my.routes"
import { OtherRoutes } from "../other/other.routes"

export default {
  MyRoutes,
  OtherRoutes,
  // ... other routes
}

Then export from the main index (packages/api-contracts/src/index.ts):

export { default as ApiRoutes } from "./api-routes/index"
export { MyRoutes } from "./my/my.routes"
export { OtherRoutes } from "./other/other.routes"

Why this pattern?

• Type safety: Route paths and response types are centralized and type-checked
• Single source of truth: Routes are defined once and reused
• Client generation: Routes can be used for generating type-safe API clients
• Consistency: All controllers follow the same pattern

Example - Complete Flow:

1. Create routes file (packages/api-contracts/src/me/me.routes.ts):

import type { MeResponseDto } from "./me.dto"
import type { ResponseData } from "../generic"
import { defineRoute } from "../helpers"

export const MeRoutes = {
  getMe: defineRoute<ResponseData<MeResponseDto>>({
    path: "me",
    method: "get",
  }),
}

2. Use in controller (apps/api/src/me/me.controller.ts):

import { Controller, Get, Req } from "@nestjs/common"
import { MeRoutes } from "@caseai-connect/api-contracts"

@Controller()
export class MeController {
  @Get(MeRoutes.getMe.path)
  async getMe(@Req() request): Promise<typeof MeRoutes.getMe.response> {
    return {
      data: {
        user: { ... },
      },
    }
  }
}

3. Export in index (packages/api-contracts/src/api-routes/index.ts):

import { MeRoutes } from "../me/me.routes"

export default {
  MeRoutes,
}

And in the main index (packages/api-contracts/src/index.ts):

export { default as ApiRoutes } from "./api-routes/index"
export { MeRoutes } from "./me/me.routes"

Testing Requirements

E2E Tests for Control