Merge pull request #63 from NavigoLearn/master

Master to prod

Author: sopyb

CODE_OF_CONDUCT.md

@@ -0,0 +1,47 @@
+# NavigoLearn Code of Conduct
+
+## Our Pledge
+
+In the spirit of fostering an open and welcoming environment, we, as contributors and maintainers, pledge to make participation in our project and our community a harassment-free experience for everyone. This commitment applies regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+NavigoLearn is a community-driven and open-source project that aims to share knowledge and experiences in programming. Our goal is to create a supportive and inclusive space where everyone can freely share their love for learning and programming.
+
+## Our Standards
+
+Positive behavior contributions include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Accepting constructive criticism graciously
+* Prioritizing the best interests of the community
+* Demonstrating empathy towards other community members
+
+Unacceptable behaviors include:
+
+* Use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate corrective action in response to any instances of unacceptable behavior.
+
+Maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this code of conduct.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and also applies when an individual is representing the project or its community in public spaces. Examples of representing the project include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative online or offline.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior can be reported to the project team at [navigolearn@gmail.com](mailto:navigolearn@gmail.com).
+
+All complaints will be reviewed and investigated and will result in a response that is considered necessary and appropriate to the circumstances.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions imposed by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available [here](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html)

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Welcome Aboard, Contributor!
+
+Hello! We are thrilled to see you here and greatly appreciate your interest in contributing to the NavigoLearn API. Here, we've set up a few guidelines to make the contribution process smooth sailing.
+
+## Code of Conduct
+
+First off, we ask all contributors to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). Please ensure you read and understand it before participating in our community.
+
+## Prepare for Your Journey
+
+If you're new to our codebase, we've got you covered. Refer to the setup guide provided in the [README.md](README.md) file. This will help you set up your local development environment and get you started on your journey with us.
+
+## Set Sail for Contribution
+
+1. **Fork the Repository** - Start by creating a fork of our repository to your account, then clone it to your local machine for direct access.
+
+2. **Gear Up Your Development Environment** - Make a new branch for your amazing feature or perhaps that clever bug fix (try to name the branch something descriptive!).
+
+3. **Chart Your Changes** - Now, you're all set to modify the necessary files to implement your magic. Make sure to follow any guidelines in the [Internal Documentation](docs/internal/README.md) and [API Reference](docs/api_reference/README.md) to ensure your changes are consistent with the rest of the codebase. Also, make sure to add any new files to the appropriate documentation files or ask for help regarding writing documentation.
+
+4. **Test the Waters** - Make sure to test your changes. If you can, add tests that cover your changes.
+
+5. **Submit a Pull Request** - You can now push your changes to your fork and submit a pull request to the `master` branch in our GitHub repository.
+
+Kindly ensure your PR has a detailed summary of changes. Discuss the problem you're tackling, identify the solution you've come up with, and share a concise and illustrative rationale for your changes.
+
+## Style Guidelines & Naming Conventions
+
+Consistency is key, and a clean, uniform codebase is a joy to work with. For our TypeScript project, we use ESLint to enforce code standards and catch potential issues.
+
+Api endpoints are named using kebab-case. For example, `GET /api/users/profile-picture` is a valid endpoint.
+
+For functions, variables and SQL tables, we use camelCase. For example, `db.getWhere('roadmapLikes', 'userId', userId, 'roadmapId', roadmapId);` is valid.
+
+### ESLint
+
+Before you submit your pull request, ensure your changes pass ESLint without any errors. If any ESLint warnings remain, they should be few and justifiable with clear explanation. Make sure to include any explanation or justification for unresolved ESLint warnings in your pull request comments.
+
+We recommend running `npm run lint`(/src) and `npm run lint:tests`(/spec) locally before pushing your changes. This will invoke ESLint and report any issues.
+
+Thank you for helping us maintain a consistent and clean codebase!
+
+## Release Shore Ahead
+
+We typically cut loose new releases every few weeks. Rest assured, once your changes have merged, they'll find their rightful place in our next release.
+
+Thank you for setting sail with us! Your contribution helps make NavigoLearn API the treasure it is.

README.md

@@ -1,4 +1,4 @@
-# Navigo Learn API
+# NavigoLearn API
 
 | Build Status |                                                  Badge                                                   |
 |:------------:|:--------------------------------------------------------------------------------------------------------:|
@@ -20,14 +20,17 @@ MariaDB.
 
 ## Documentation
 
-Documentation for the api can be found [here](docs/paths/README.md).
+- [API endpoint reference](./docs/api_reference/README.md)
+- [Internal documentation](./docs/internal/README.md)
+- [Contributing guidelines](./CONTRIBUTING.md)
+- [Code of conduct](./CODE_OF_CONDUCT.md)
 
 # Getting Started
 
 ## Prerequisites
 
-- [Node.js](https://nodejs.org/en/) - v16 or higher
-- [MariaDB](https://mariadb.org/) - v10.6 or higher
+- [Node.js](https://nodejs.org/en/) - v18 or higher
+- [MariaDB](https://mariadb.org/) - v10.11 or higher
 - [Git](https://git-scm.com/) - v2.32 or higher
 
 ## Installation
@@ -61,32 +64,4 @@ Documentation for the api can be found [here](docs/paths/README.md).
 6. Run the server
    ```sh
    npm run dev
-   ```
-
-## Structure of the Project
-
-The project is split into 4 main folders:
-
-- `src` - Contains all the source code for the project.
-- `spec` - Contains all the unit-tests for the project.
-- `docs` - Contains all the documentation for the project.
-- `env` - Contains all the environment files for the project. (rename the
-  env.example folder to env to use it)
-
-### `src`
-
-The `src` folder is split into multiple main folders:
-
-- `constants` - Contains constants used in the project. (HTTP status codes, env
-  variables, etc.)
-- `controllers` - Contains the controllers of the project.
-- `middleware` - Contains middleware used in the project. (session, etc.)
-- `models` - Contains the data models for the project. (Roadmap, User, etc.)
-- `routes` - Contains the routers pointing to controllers. (auth, users, etc.)
-- `sql` - Contains sql files used in the project. (create tables, metrics, etc.)
-- `utils` - Contains utility functions used in the project. (databaseDriver,
-  etc.)
-- `validators` - Contains the validators used in the project. (user, roadmap,
-  etc.)
-- `index.ts` - The entry point.
-- `server.ts` - The server.
+   ```

docs/README.md

@@ -1,10 +1,28 @@
-# Navigo API Documentation
+# Documentation
 
-This is the documentation for the Navigo API. It is a RESTful API that allows
-you to create, read, update and delete data from the Navigo database.
+This directory contains detailed documentation for the NavigoLearn API.
 
 ## Table of Contents
 
-### 1. [Paths](paths/README.md)
+- [API Reference](./api_reference/README.md)
+- [Internal Architecture](./internal/README.md)
+- [Contribution Guidelines](../contributing.md)
+- [Code of Conduct](../CODE_OF_CONDUCT.md)
 
-### 2. [Types](types/README.md)
+## Overview
+
+### API Reference
+
+The [API Reference](./api_reference/README.md) directory provides a detailed reference of all API endpoints. For each endpoint, you will find its parameters and the response it delivers.
+
+### Internal Architecture
+
+The [Internal Architecture](./internal/README.md) directory is meant for developers who want to understand the codebase and possibly contribute. It includes detailed explanations about the API's models, controllers, routes, middleware, and other components.
+
+### Contribution Guidelines
+
+We love contributions from our community! The [Contribution Guidelines](../contributing.md) provide information on our code style guidelines and the Git workflow to be followed to contribute to this project.
+
+### Code of Conduct
+
+We expect all contributors to abide by our [Code of Conduct](../CODE_OF_CONDUCT.md). Please ensure you read and understand it before participating in our community.

docs/api_reference/README.md

@@ -0,0 +1,85 @@
+# API Reference
+
+This directory provides detailed documentation of each endpoint in the NavigoLearn API.
+
+
+
+## Overview
+
+For each endpoint, we provide the following details:
+
+- The HTTP method (GET, POST, PUT, DELETE)
+- Endpoint URL
+- Required parameters in the request
+- A short description of what the endpoint does
+- An example request
+- An example response
+
+## Endpoints
+
+- /api
+  - /api/auth
+    - [GET /api/auth/google-login](./auth/google-login.md)
+    - [GET /api/auth/google-callback](./auth/google-callback.md)
+    - [GET /api/auth/github-login](./auth/github-login.md)
+    - [GET /api/auth/github-callback](./auth/github-callback.md)
+    - [POST /api/auth/login](./auth/login.md)
+    - [POST /api/auth/register](./auth/register.md)
+    - [POST /api/auth/change-password](./auth/change-password.md)
+    - [POST /api/auth/forgot-password](./auth/forgot-password.md) (Not Implemented - Not planned)
+    - [DELETE /api/auth/logout](./auth/logout.md)
+  - /api/search (formerly /api/explore)
+    - [GET /api/search/roadmaps](./search/roadmaps.md)
+    - [GET /api/search/feeling-lucky](./search/feeling-lucky.md)
+    - ... More to be added
+  - /api/roadmaps
+    - [GET /api/roadmaps/:roadmapId](./roadmaps/get-roadmap.md)
+    - [POST /api/roadmaps/create](./roadmaps/create-roadmap.md)
+    - /api/roadmaps/:roadmapId
+      - **Update roadmap data**
+      - [POST /api/roadmaps/:roadmapId/](./roadmaps/update-roadmap.md)
+      - [POST /api/roadmaps/:roadmapId/about](./roadmaps/update-roadmap-about.md)
+      - [POST /api/roadmaps/:roadmapId/name](./roadmaps/update-roadmap-name.md)
+      - [POST /api/roadmaps/:roadmapId/description](./roadmaps/update-roadmap-description.md)
+      - [POST /api/roadmaps/:roadmapId/topics](./roadmaps/update-roadmap-topic.md)
+      - [POST /api/roadmaps/:roadmapId/draft](./roadmaps/update-roadmap-draft.md)
+      - [POST /api/roadmaps/:roadmapId/version](./roadmaps/update-roadmap-version.md)
+      - [POST /api/roadmaps/:roadmapId/data](./roadmaps/update-roadmap-data.md)
+      - [POST /api/roadmaps/:roadmapId/misc-data](./roadmaps/update-roadmap-misc-data.md)
+      - **Interact with the roadmap**
+      - [GET /api/roadmaps/:roadmapId/like](./roadmaps/like-roadmap.md)
+      - [GET /api/roadmaps/:roadmapId/dislike](./roadmaps/unlike-roadmap.md)
+      - [GET /api/roadmaps/:roadmapId/progress](./roadmaps/get-roadmap-progress.md)
+      - [POST /api/roadmaps/:roadmapId/progress](./roadmaps/update-roadmap-progress.md)
+      - [DELETE /api/roadmaps/:roadmapId/{like,dislike}](./roadmaps/delete-roadmap-like.md)
+    - [DELETE /api/roadmaps/:roadmapId](./roadmaps/delete-roadmap.md)
+  - /api/users
+    - [GET /api/users/:userId?](./users/get-user.md)
+    - [GET /api/users/:userId/mini](./users/get-user-mini.md)
+    - [GET /api/users/:userId/roadmaps](./users/get-user-roadmaps.md)
+    - [GET /api/users/:userId/follow](./users/follow-user.md) 
+    - [DELETE /api/users/:userId/follow](./users/unfollow-user.md)
+    - [POST /api/users/](./users/update-user.md)
+    - [POST /api/users/name](./users/update-user-name.md)
+    - [POST /api/users/profile-picture](./users/update-user-profile-picture.md) (Not Implemented - Not plan)
+    - [POST /api/users/bio](./users/update-user-bio.md)
+    - [POST /api/users/quote](./users/update-user-quote.md)
+    - [POST /api/users/website-url](./users/update-user-website-url.md)
+    - [POST /api/users/github-url](./users/update-user-github-url.md) (To be added)
+    - [DELETE /api/users/:userId](./users/delete-user.md)
+
+## Responses
+
+All responses are in JSON format and have the keys `success` and `message`. The `success` key is a boolean that indicates whether the request was successful or not. The `message` key is a string that contains a message about the request. If the request was successful, the `message` key will contain a confirmation message. If the request was unsuccessful, the `message` key will contain an error message.
+
+Additionally, some responses will contain a `data` key. The `data` key will contain the data requested by the user. For example, if the user requests a roadmap, the `data` key will contain the roadmap data.
+
+Also, some responses will contain a `total` key. The `total` key will contain the total number of items that match the response `data` array. For example, if the user requests a list of roadmaps, the `total` key will contain the total number of roadmaps that match the request.
+
+**Each response file above contains an example response.**
+
+## Note
+
+Please note that this API reference is a work in progress and will continue to grow as new endpoints are added to the NavigoLearn API.
+
+And some might change requirements or functionality as the project evolves.

docs/api_reference/auth/change-password.md

@@ -0,0 +1,49 @@
+# POST /api/auth/change-password
+
+## Description
+
+This endpoint is used to change the password of a user.
+
+## Request
+
+### Parameters
+
+None
+
+### Body
+
+```json
+{
+  "password": "string",
+  "newPassword": "string"
+}
+```
+
+### Headers
+
+- 'cookie': 'token=...' (Must be valid)
+
+## Response
+    
+```json
+{
+    "success": true,
+    "message": "Password changed successfully"
+}
+```
+
+### Response Codes
+
+Example:
+
+| Code | Description            |
+|------|------------------------|
+| 200  | Success                |
+| 400  | Bad Request.           |
+| 401  | Unauthorized.          |
+| 429  | Too Many Requests      |
+| 500  | Internal Server Error. |
+
+### Cookies
+
+None

docs/api_reference/auth/forgot-password.md

@@ -0,0 +1 @@
+# Not Implemented - Not planned

docs/api_reference/auth/github-callback.md

@@ -0,0 +1,45 @@
+# GET /api/auth/github-callback
+
+## Description
+
+This endpoint is used as a callback URL for GitHub OAuth2.0 authentication. It is called by GitHub after the user has successfully authenticated with GitHub.
+
+## Request
+
+### Parameters
+
+See [GitHub OAuth2.0 documentation](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#2-users-are-redirected-back-to-your-site-by-github) for more information.
+
+- `code`: The authorization code returned by GitHub after the user has successfully authenticated with GitHub.
+
+### Body
+
+None
+
+### Headers
+
+None
+
+## Response
+
+```json
+{
+  "success": true,
+  "message": "Login successful"
+}
+```
+
+### Response Codes
+
+Example:
+
+| Code | Description            |
+|------|------------------------|
+| 200  | Success                |
+| 201  | Created                |
+| 400  | Bad Request            |
+| 500  | Internal Server Error. |
+
+### Cookies
+
+- `token` (optional): The JWT token that is used to authenticate the user. This cookie is only set if the user successfully authenticated with GitHub.