Tracker CRM by Turing School of Software and Design

Overview

This app is a Rails backend API for a job tracking CRM tool.

Setup

Rails 7.1.5 Ruby 3.2.2

bundle install

rails db:create
rails db:migrate
rails db:seed

This app will run on port 3001 locally.

Testing

This app uses RSpec for testing.

bundle exec rspec

API Documentation

Users

Create a User

New users require a unique email address and a matching password and password confirmation.

Request:

POST /api/v1/users

Body:
{
  "name": "John Doe",
  "email": "[email protected]",
  "password": "password",
  "password_confirmation": "password"
}

Successful Response:

Status: 201 Created
Body: {
    "data": {
        "id": "4",
        "type": "user",
        "attributes": {
            "name": "John Doe",
            "email": "[email protected]"
        }
    }
}

Error Responses:

Status: 400 Bad Request
Body: {
    "message": "Email has already been taken",
    "status": 400
}

Status: 400 Bad Request
Body: {
    "message": "Password confirmation doesn't match Password",
    "status": 400
}

Get All Users

Request:

GET /api/v1/users

Successful Response:

Status: 200 OK
Body: {
    "data": [
        {
            "id": "1",
            "type": "user",
            "attributes": {
                "name": "Danny DeVito",
                "email": "danny_de_v"
            }
        },
        ...
        {
            "id": "4",
            "type": "user",
            "attributes": {
                "name": "John Doe",
                "email": "[email protected]"
            }
        }
    ]
}

Get a User

Request:

GET /api/v1/users/:id

Successful Response:

Status: 200 OK
Body: {
    "data": {
        "id": "3",
        "type": "user",
        "attributes": {
            "name": "Lionel Messi",
            "email": "futbol_geek"
        }
    }
}

Update a user

Request:

PUT /api/v1/users/:id

Body:
{
  "name": "John Doe",
  "email": "[email protected]",
  "password": "password",
  "password_confirmation": "password"
}

Successful Response:

Status: 200 OK
Body: {
    "data": {
        "id": "4",
        "type": "user",
        "attributes": {
            "name": "Nathan Fillon",
            "email": "firefly_captian"
        }
    }
}

Error Responses:

Status: 400 Bad Request
Body: {
    "message": "Email has already been taken",
    "status": 400
}

Status: 400 Bad Request
Body: {
    "message": "Password confirmation doesn't match Password",
    "status": 400
}

Create a Session (Login)

Request:

POST /api/v1/sessions

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

Successful Response:

Status: 200 OK

Body: {
    "data": {
        "id": "4",
        "type": "user",
        "attributes": {
            "name": "John Doe",
            "email": "[email protected]"
        }
    }
}

Error Response:

Status: 401 Unauthorized

Body: {
    "message": "Invalid login credentials",
    "status": 401
}

Job Applications

Create a Job Application

Request:

POST /api/v1/users/:user_id/job_applications

Body: {
    {
        position_title: "Jr. CTO",
        date_applied: "2024-10-31",
        status: 1,
        notes: "Fingers crossed!",
        job_description: "Looking for Turing grad/jr dev to be CTO",
        application_url: "www.example.com",
        contact_information: "[email protected]",
        company_id: id_1
      }
}

Successful Response:


Status: 200

{:data=>
  {:id=>"4",
   :type=>"job_application",
   :attributes=>
    {:position_title=>"Jr. CTO",
     :date_applied=>"2024-10-31",
     :status=>1,
     :notes=>"Fingers crossed!",
     :job_description=>"Looking for Turing grad/jr dev to be CTO",
     :application_url=>"www.example.com",
     :contact_information=>"[email protected]",
     :company_id=>35}}
     }

Unsuccessful Response:

{:message=>"Company must exist and Position title can't be blank", :status=>400}

Unsuccessful Response(pre-existing application for user):

{:message=>"Application url You already have an application with this URL", :status=>400}

Companies

Get login credentials

Request:

POST /api/v1/sessions

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

Successful Response:

Status: 200 OK

This response will have a token like this:
eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJleHAiOjE3MzM0MzUzMDJ9.O6FtfoVjcobUiBHfKmZNovtt57061ktlPx-UgIZFGaQ

Body: {
    "data": {
        "id": "4",
        "type": "user",
        "attributes": {
            "name": "John Doe",
            "email": "[email protected]"
        }
    }
}

Error Response if no token provided:

Status: 401 Unauthorized

Body: {
    "message": "Invalid login credentials",
    "status": 401
}

Create a company

Request:

post "/api/v1/users/userid/companies" 

Add the bearer token to the auth tab in postman and will be able to create a company now for that specific user. Make sure to have the token for that user.

raw json body: 
{
  "name": "New Company",
  "website": "www.company.com",
  "street_address": "123 Main St",
  "city": "New York",
  "state": "NY",
  "zip_code": "10001",
  "notes": "This is a new company."
}

Successful Response:

Status: 201 created

"data": {
        "id": "1",
        "type": "company",
        "attributes": {
            "name": "New Company",
            "website": "www.company.com",
            "street_address": "123 Main St",
            "city": "New York",
            "state": "NY",
            "zip_code": "10001",
            "notes": "This is a new company."
    }
}

Error response - missing params

Request:

{
    "name": "", 
    "website": "amazon.com", 
    "street_address": "410 Terry Ave N", 
    "city": "Seattle", 
    "state": "WA", 
    "zip_code": "98109", 
    "notes": "E-commerce"
}

Response:

{
    "message": "Name can't be blank",
    "status": 422
}

Get all companies

Request:

GET /api/v1/users/userid/companies

Authorization: Bearer Token - put in token for user

Successful Response:

Body:{
  {
    "data": [
        {
            "id": "1",
            "type": "company",
            "attributes": {
                "name": "Google",
                "website": "google.com",
                "street_address": "1600 Amphitheatre Parkway",
                "city": "Mountain View",
                "state": "CA",
                "zip_code": "94043",
                "notes": "Search engine"
            }
        },
        {
            "id": "2",
            "type": "company",
            "attributes": {
                "name": "New Company122",
                "website": "www.company.com",
                "street_address": "122 Main St",
                "city": "New York11",
                "state": "NY11",
                "zip_code": "10001111",
                "notes": "This is a new company111."
            }
        }
    ]
}
}

User with no companies:

{
    "data": [],
    "message": "No companies found"
}

No token or bad token response

{
    "error": "Not authenticated"
}

Contacts

Get login credentials:
Refer to Companies "Get login credentials" above

Get all contacts for a user

Request:

GET /api/v1/users/:user_id/contacts

Authorization: Bearer Token - put in token for user

Successful Response:

{
  "data": [
    {
      "id": "1",
      "type": "contacts",
      "attributes": {
        "first_name": "John",
        "last_name": "Smith",
        "company": "Turing",
        "email": "[email protected]",
        "phone_number": "(123) 555-6789",
        "notes": "Type notes here...",
        "user_id": 4
      }
  },
  {
    "id": "2",
    "type": "contacts",
    "attributes": {
      "first_name": "Jane",
      "last_name": "Smith",
      "company": "Turing",
      "email": "[email protected]",
      "phone_number": "(123) 555-6789",
      "notes": "Type notes here...",
      "user_id": 4
      }
    }
  ]
}

Successful response for users without saved contacts:

{
  "data": [],
  "message": "No contacts found"
}

Create a contact with required and optional fields.

New contacts require a unique first and last name. All other fields are optional.

Request:

POST /api/v1/users/:user_id/contacts
Authorization: Bearer Token - put in token for user

raw json body with all fields: 

{
  "contact": {
    "first_name": "Jonny",
    "last_name": "Smith",
    "company_id": 1,
    "email": "[email protected]",
    "phone_number": "555-785-5555",
    "notes": "Good contact for XYZ",
    "user_id": 7
  }
}

Successful Response:

Status: 201 created

{
    "data": {
        "id": "5",
        "type": "contacts",
        "attributes": {
            "first_name": "Jonny",
            "last_name": "Smith",
            "company_id": 1,
            "email": "[email protected]",
            "phone_number": "555-785-5555",
            "notes": "Good contact for XYZ",
            "user_id": 7
        }
    }
}

Contact Errors

401 Error Response if no token provided:

Status: 401 Unauthorized

Body: {
    "message": "Invalid login credentials",
    "status": 401
}

422 Error Response Unprocessable Entity: Missing Required Fields If required fields like first_name or last_name are missing:

Request:

POST /api/v1/users/:user_id/contacts
Authorization: Bearer Token - put in token for user

raw json body:

 {
  "contact": {
    "first_name": "Jonny",
    "last_name": ""
  }
}

Error response - 422 Unprocessable Entity

{
    "error": "Last name can't be blank"
}

Error response - invalid email format

Request:

{
  "contact": {
    "first_name": "Johnny",
    "last_name": "Smith",
    "email": "invalid-email"
  }
}

Response: 422 Unprocessable Entity

{
    "error": "Email must be a valid email address"
}

Error response - invalid phone number format

Request:

{
  "contact": {
    "first_name": "Johnny",
    "last_name": "Smith",
    "email": "invalid-email"
  }
}

Response: 422 Unprocessable Entity

{
    "error": "Phone number must be in the format '555-555-5555'"
}

Authentication, User Roles, and Authorization

Authentication is handled by the JWT(Json Web Token) Gem
User Roles is handled by the Rolify Gem
Authorization is enforced by the Pundit Gem
Installation
1. Pull the latest changes to your branch git pull origin main resolve merge conflicts
2. Bundle Install and Migrate bundle install then rails db:migrate
3. Run bundle exec rspec spec/ and note what requests tests are now failing
4. Refactor controllers, their associated _spec.rb files. Make policies for corresponding controllers (app/policies/_policy.rb) and test policies
5. Use examples in UserPolicy, ApplicationPolicy, UsersController, ApplicationController and all corresponding spec files.
Important Schema Note
- This branch introduces 2 new tables to our db schema - roles and users_roles that were generated by Rolify:
  - roles table has name, resouce_type and resource_id. Name string is the name of the role and can either be ["admin"] OR ["user"]. Resource type string is an optional polymorphic association that specifies the type of resource the role applies to (company, job, contact).
    - Whenever a user is created, they are automatically assigned a role[:name] of ["user"]
  - users_roles is a join table for the many-to-many relationship between users and roles.
Understanding JWT(Json Web Token) Gem

We now use JSON Web Tokens for user authentication. Here's what to know:
- Key Concepts
  - Token-Based Authentication
    - Upon login, a JWT is issued to the registered user.
    - The token must be included in the Headers for every authenticated request in Postman.
      - Authorization: Bearer <jwt_token>
    - The token encodes a payload that contains:
      - User's id
      - User's role (either "admin" or "user")
      - Tokens expiration time (24 hours after issue)
  - Changes made in Codebase
    - ApplicationController now has 2 new methods:
      - authenticate_user ensures tokens validity and corresponds to a logged-in user.
      - decoded_token(token) to extract info from token
      - All controllers will inherit this logic.
    - SessionsController
      - Handles login and session creation
      - #create action:
        
        Verifies user's credentials
        
        generate_token(payload) generates an encoded JWT using above-mentioned payload
        
        Sends the token back in the response
Understanding the Rolify Gem

Rolify simplifies the management of user roles by introducing a flexible, role-based system. This gem created the roles and users_roles tables.
- Key Concepts
  - When a new user is created, they are automatically assigned the user role.
  - Methods in user.rb created as querying and setting shortcuts:
    - assign_default_role is called to set a user's role to :user upon a new instance of User being created. All new users will get role :user.
    - is_admin? and/or is_user? queries any user's role
    - set_role(role_name) assigns a specific role to a user(e.g user1.set_role(:admin) will set a user to the :admin role)
  - For future scalability, polymorphic roles can be scoped to specific users. For example, we can add in a :moderator role in the future that would be an :admin for only the company table. Enabled by resource_type and resource_id fields in roles table.
- Usage in Codebase
  - In your models where roles are needed (e.g., User, Company), use: resourcify at the top of the class(near validations/relations) to make the model "role-aware" and capable of interacting with Rolify
  - Use above-mentioned methods in user.rb to query and set user roles.
- How this affected the Codebase
  - UsersController now leverages roles to restrict access. For example, only an :admin can view all users (subject to change, ofc)
  - ApplicationPolicy Includes logic to ensure actions are authorized based on roles.
  - Affects RSpec testing to test role-based permitted controller actions (see index_spec.rb ln:7 for an example)
Understanding the Pundit Gem

Pundit enforces authorization through policy classes and ensures that only authorized users can perform specific actions. To fully understand Pundit, you must understand what a policy is:
- A policy is a PORO that defines the rules governing what actions a user is authorized to perform on a resource (e.g., User, Job, Company). Each policy corresponds to a model's controller and centralizes the access control logic for that resource.
- I have set up UserPolicy for it's corresponding UsersController as a template for all to use. UserPolicy restricts which CRUD actions a user can use depending on that user's role. All of Users associated request spec files have also been refactored to pass and are a template for you.
- Key Concepts
  - Policy Classes as mentioned above define an action a user can take
    - stored in app/policies and inherit from ApplicationPolicy
    - Policies are then passed to ApplicationController via include Pundit::Authorization ln:2. Remember that all controllers inherit from ApplicationController unless explicitly told not to.
  - Authorization Logic
    - Authorization is defined in methods corresponding to controller actions (e.g., create?, update?).
    - ApplicationPolicy provides a default template where ALL actions are unauthorized by default.
    - Use UserPolicy (and it's associated spec file for testing) as a template for making your controller's policies.
  - Scoping
    - Policies include a nested Scope class (see UserPolicy) to define which records a user can access when retrieving a collection.
- Usage in Codebase
  - Use the authorize method IN your controller action code blocks to enforce policy checks (see UsersController ln: 5, 15, 21, 28 for examples. Yes, it is THAT easy :))
  - If a user is unauthorized, Pundit raises a Pundit::NotAuthorizedError in your console RSpec testing suite.
  - For testing, refer to user_policy_spec.rb as a template. Note that ln:3 subject { described_class } subject == UserPolicy
  - Policies integrate with Rolify to check user roles
In conclusion
```
  - JWT secures the app by ensuring only authenticated users can access resources.
  - Rolify manages who can act (roles), while Pundit manages what they can do (authorization).
  - Refactoring controllers and policies is critical to aligning with this new system.
  - Ensure all tests are updated to reflect these changes, including controller specs and new policy tests.
  - It is up to you, as you develop to keep in mind what actions users are authorized to take.  :Admin role users should be authorized to do anything.
```

Name		Name	Last commit message	Last commit date
Latest commit History 119 Commits
.github		.github
app		app
bin		bin
config		config
db		db
lib/tasks		lib/tasks
log		log
public		public
spec		spec
storage		storage
tmp		tmp
vendor		vendor
.DS_Store		.DS_Store
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.rspec		.rspec
.rubocop.yml		.rubocop.yml
.ruby-version		.ruby-version
Dockerfile		Dockerfile
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
README.md		README.md
Rakefile		Rakefile
config.ru		config.ru

turingschool/tracker-crm

Folders and files

Latest commit

History

Repository files navigation

Tracker CRM by Turing School of Software and Design

Overview

Setup

Testing

API Documentation

Users

Create a User

Get All Users

Get a User

Update a user

Create a Session (Login)

Job Applications

Create a Job Application

Companies

Create a company

Get all companies

Contacts

Get all contacts for a user

Create a contact with required and optional fields.

Contact Errors

Authentication, User Roles, and Authorization

Installation

Important Schema Note

Understanding JWT(Json Web Token) Gem

Key Concepts

Understanding the Rolify Gem

Key Concepts

Usage in Codebase

How this affected the Codebase

Understanding the Pundit Gem

Key Concepts

Usage in Codebase

In conclusion

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Contributors 10

Languages

Packages