Description

Installation

1. Open your terminal and run the following command:

   npm install @appxdigital/appx-core-cli -g
   appx-core create

2. Follow the prompts provided by the setup wizard. This will scaffold a new NestJS project with appx-core pre-integrated.
3. Open created project in your favorite IDE.

Configure Database Schema

1. Open the prisma/schema.prisma file.
2. Modify this file to define your application's specific data models. You can add new models, fields, and relations as needed.

Note: If you already have a database created and want to import the structure, use the following command:

npx prisma db pull

This command will override the schema.prisma file, please ensure that the original configurations and models are kept (you can adapt User and Session model, but it's advised to keep all default attributes)

Generate Modules and Prisma Client

1. After editing your schema, generate the modules for each model by running:

   appx-core generate

2. This command also updates the @prisma/client library within your node_modules to match your defined schema, providing type-safe database access. This command should be run everytime you make a change to your prisma schema.

Apply Database Migrations

1. To create the necessary database tables and apply your schema changes, run:

   npx prisma migrate dev

2. This will:
   • Create a new SQL migration file reflecting the changes between your current schema and the last migration.
   • Apply the migration to your database.

Run the Application

1. Start your application in development mode using:

   npm run start:dev

2. The application will start on http://localhost:3000 or the port specified during your setup, you can change this in the .env file.

Register Your First User

1. To create a user account, send an HTTP POST request to the /auth/register endpoint.
2. The request body must be JSON and include the email and password:

   {
     "email": "[email protected]",
     "password": "password"
   }

3. On success, you'll receive a JSON response confirming registration and containing the new user's details.

Log In

1. To log in with the registered user, send an HTTP POST request to the /auth/login endpoint.
2. The request body must be JSON and include the same fields used for registration:

   {
     "email": "[email protected]",
     "password": "password"
   }

3. On success, you'll receive a JSON response confirming login and containing the user's details.

Permissions

This project uses RBAC to control user access. Permissions are defined in a configuration file and checked automatically before controller actions and during database queries.

Configuration

• Permissions are defined in the src/config/permissions.config.ts file.

• The configuration structure is hierarchical: ModelName -> RoleName -> ActionName -> Rule.

  export const PermissionsConfig: PermissionsConfigType = {
    ModelName: { // e.g., 'User'; links to controller's entityName
      RoleName: { // e.g., 'ADMIN', 'CLIENT'; matches user roles
        ActionName: Rule, // e.g., 'findUnique', 'update'
        // ... other actions for this role/model
      },
       // ... other roles for this model
    },
    // ... other models
  };

Permission Rules & Effects

The Rule assigned to an action determines if a user with that role can perform the action:

• 'ALL': Grants unrestricted access for the specific action.
• Object { conditions: { ... } }: Grants access only if the specified conditions match the data being accessed.
  • These conditions (e.g., { id: '$USER_ID' }) are automatically added as WHERE clauses to the underlying database query by the PrismaService.
  • Placeholders like $USER_ID are replaced with the current user's actual data (e.g., req.user.id).
• Missing Rule: If no rule ('ALL' or an object) is defined for an action under the user's role, access is denied.

Applying Permissions

• Protect controller methods by decorating them with @Permission('actionName'). This links the method to an ActionName in your permissions.config.ts.

  • Methods without the @Permission decorator are not subject to specific action checks by the RbacGuard and are allowed access.

    @Controller('users')
    export class UserController extends CoreController<User>  {  
    
      @Get(':id')
      @Permission('findUnique') // Checks config for User -> Role -> findUnique
      async findOne(@Param('id') id: string) {
        /* ... */
      }
    
      @Get('/public/info')
      // No @Permission decorator - RbacGuard allows by default access for this route
      async getPublicInfo() { 
        /* ... */ 
      }
          
       static get entityName(): string {
        return 'User';
      }
    }

Adding Permissions for a New Action

1. Decorate Method & Choose Name: Add the @Permission('yourActionName') decorator to the relevant controller method, choosing a unique string for 'yourActionName' (e.g., 'publishItem', 'resetPassword').

2. Update Config: Edit permissions.config.ts. Add the actionName under the appropriate ModelName -> RoleName(s). Set the rule:

   • Use 'ALL' for full access.
   • Use an object like { conditions: { field: '$USER_ID' } } for conditional access (enforced by the database query).

   // Example: Adding 'publishItem' rule to Article model config
     Article: {
       ADMIN: { /*...,*/ publishItem: 'ALL' },
       EDITOR: { /*...,*/ publishItem: { conditions: { authorId: '$USER_ID' } } },
     },