docs: docs improvement for integrating apps and local setup (#509)

* Update add-integration-guide.mdx

* Update developer-guides.mdx

fern/docs/contents/add-integration-guide.mdx

@@ -1,21 +1,27 @@
-
-### How to contribute an integration to Revert
+## How to contribute an integration to Revert
 
 **1.** Ensure that the project is configured in the local environment following the instructions outlined [here](https://github.com/revertinc/revert/blob/main/CONTRIBUTING.md). Establish a connection to an existing application and test various [endpoints](https://docs.revert.dev/api-reference) to verify proper functionality.
 
+To establish the connection with one of the app,watch this video of ClickUp integration [ClickUp Integration](https://www.loom.com/share/1d8947425bcc49af89f210555a50f441?sid=51ad2d45-514a-4536-ac62-772a069cb4a7) and follow the other steps in the "Test Your Integration" section below.
+
 **2.** Analyze the authentication and authorization flow based on the requirements of the third-party API. Identify the appropriate authentication type, which may include options such as Basic, OAuth 2.0, OAuth 1.0, API Key, etc depending on the thirdparty.
 
-**3.** Incorporate your third-party integration by adding it to the Prisma TP_ID enum. Execute the command `yarn migration:dev` in `packages/backend` to apply the necessary database migrations.
+**3.** Incorporate your third-party integration by adding it to the Prisma TP_ID enum.
 
-**4.** Implement the recommended authentication and refresh token flows for the third-party integration. To generate access tokens and establish a connection, refer to the relevant code in `packages/backend/routes/v1/` within respective sub-packages like `crm, chat, ticketing, etc`. For the refresh token flow, inspect the methods available in `packages/backend/services/auth.ts`, for categorized token-refreshing methods such as `refreshOAuthTokensForThirdParty` and `refreshOAuthTokensForThirdPartyTicketServices`.
+**4.** Incorporate the designated value as a string (previously set in the `TP_ID` enum in the Prisma schema) within the suitable category in both `packages/backend/common.ts` and `packages/backend/prisma/seed.ts`.
 
-> If you are introducing a new category that lacks a corresponding structure in the project, feel free to create new packages as needed. Should you require assistance, please don't hesitate to reach out to us on [Discord](<(https://discord.gg/q5K5cRhymW)>).
+**5.** Execute the command `yarn workspace @revertdotdev/backend migration:dev` to apply the necessary database migrations.Also run this to seed the new changes to db tables `yarn workspace @revertdotdev/backend db-seed`.
+
+> If you are making changes to prisma files and you want the data in the db tables for proper functionality of the feature you are working on, then always seed the db.
 
-**5.** Incorporate the designated value as a string (previously set in the `TP_ID` enum in the Prisma schema) within the suitable category in both `packages/backend/common.ts` and `packages/backend/prisma/seed.ts`.
+**6.** Implement the recommended authentication and refresh token flows for the third-party integration. To generate access tokens and establish a connection, refer to the relevant code in `packages/backend/routes/v1/` within respective sub-packages like `crm, chat, ticketing, etc`. For the refresh token flow, inspect the methods available in `packages/backend/services/auth.ts`, for categorized token-refreshing methods such as `refreshOAuthTokensForThirdParty` and `refreshOAuthTokensForThirdPartyTicketServices`.
+If your integration doesn't have a refresh token mechanism,study the absent integrations in the above files and proceed similarly.
 
-**6.** Prior to Unification, when implementing any given endpoint, initiate the process by generating a fern configuration for it. Ensure that thirdparty endpoint/operations for the specified API are conducted through Revert.
+> If you are introducing a new category that lacks a corresponding structure in the project, feel free to create new packages as needed. Should you require assistance, please don't hesitate to reach out to us on [Discord](<(https://discord.gg/q5K5cRhymW)>).
+
+**7.** Prior to Unification, when implementing any given endpoint, initiate the process by generating a fern configuration for it. Ensure that thirdparty endpoint/operations for the specified API are conducted through Revert.
 
-**7.** For the given endpoint(s), unify the schema and fields by implementing them in `packages/backend/prisma/fields.ts`.
+**8.** For the given endpoint(s), unify the schema and fields by implementing them in `packages/backend/prisma/fields.ts`.Seed the db here again.
 
 **Unification Process.** Performed while retrieving resources from third party to match the provided schema. The process involves the following steps:
 
@@ -30,3 +36,21 @@
 2. `flattenObj`: Extract additional values from the object.
 3. `transformModelToFieldMapping`: Convert fields to match the format accepted by the third party, which is the reverse of the `transformFieldMappingToModel` step in the unification process.
 4. `postprocessDisUnifyObject`: Modify values to align with the expectations of the third party.
+
+**9.** Add changes for your integration in the functions involved during the Unification and Disunification process.
+
+## Test Your Integration
+
+For testing your integration while integrating it with revert.
+
+-   Go to `packages/js` folder and create a new file `.env` and copy the content of `.env.example`.
+
+-   Run `yarn dev:all`
+
+- Go to `packages\react\src\App.tsx` and paste you public revert token from `localhost:3000` in place of `localPublicToken`.
+
+-   Go to `localhost:3001` and start your testing.
+
+Here's a video showing final testing of an integration.It is a video testing the ClickUp integration.
+
+[ClickUp Integration](https://www.loom.com/share/1d8947425bcc49af89f210555a50f441?sid=51ad2d45-514a-4536-ac62-772a069cb4a7)

fern/docs/contents/developer-guides.mdx

@@ -1,5 +1,3 @@
-# Requirements
-
 ## System Requirements
 
 Before you start, make sure you have the following applications and their minimum versions installed, in addition to Node.js and yarn (as mentioned earlier):
@@ -8,52 +6,66 @@ Before you start, make sure you have the following applications and their minimu
 -   **Yarn 3.0.2** or later
 -   macOS, Windows (including WSL), and Linux are supported.
 
-## System Requirements
-
 ## Get Started
 
-### setup
+### Setup
 
-1 . Clone the forked repository and open the created directory
+-   Clone the forked repository and open the created directory
 
 ```shell
 git clone https://github.com/<YOUR_GITHUB_USERNAME>/revert.git
 cd revert
 
 ```
 
-2 . Install dependencies
+-   Install dependencies
 
 ```shell
 yarn
 ```
 
-3 . backend setup
-
 # @revertdotdev/backend
 
+### Copy the example env file in `packages/backend` folder.
+
 ```shell
-# Copy the example env file
 cp packages/backend/.env.example packages/backend/.env
-
-# Update this .env file with your own secrets if you'd like to.
+# Update this .env file with your own secrets if you'd like to.PgSql and redis are must.
 ```
 
 ### Fern setup
 
 -   Login with Fern with `fern login`.
+
 -   To generate Fern drive code locally, run `yarn fern` in the root folder of this repo. This will create the `packages/backend/generated` folder with the generated code.
 
+### Fern setup fails
+
+If `yarn fern` fails to succeed, here are some temporary solutions.
+
+-   Try running `yarn fern` in wsl.
+
+-   Install fern-api globally in wsl.`npm i -g fern-api` will install fern-api globally in wsl and then in the root of this project run `fern generate`.
+
+-   Try dual booting your windows machine to ubuntu or any other linux distribution and setup the project their.
+
+-   Try to change the internet network.For eg: if you were using mobile network,try using another mobile network/different sim and try to run `yarn fern` in wsl multiple times.
+
+These solutions are not permanent, and there is no guarantee that they will work reliably in all situations.Order is not important,any one of them may work for you.
+
 ### Setup Redis
 
 -   Have a redis instance running locally or use https://upstash.com/ to get a redis url.
--   Update the redis url in `.env`
+
+-   Update the redis url in `.env`.A redis url looks like this `redis://<username>:<password>@<hostname>:<port>/<database>` . Use `rediss` instead of `redis` if you use a secure connection over TLS/SSL in redis.
 
 ### Setup PostgreSQL
 
 -   Install PostgreSQL on the system before seeding the database with sample data
+
 -   Refer https://www.postgresql.org/download/ for instructions.
--   Get a PostgreSQL url and update it in `.env`
+
+-   Get a PostgreSQL url and update it in `.env` A pgsql url looks like this `postgresql://<username>:<password>@<hostname>:<port>/<database>`
 
 ### Applying Existing Migrations
 
@@ -65,54 +77,60 @@ cp packages/backend/.env.example packages/backend/.env
 
 ### Seed the database
 
+-   Seed the database with sample data
+
 ```shell
-# seed the database with sample data
 yarn workspace @revertdotdev/backend db-seed
 ```
 
 ### Running the API locally
 
--   Run
+-   Backend service locally at `:4001`
 
 ```shell
 yarn workspace @revertdotdev/backend dev
 ```
 
-to the run service locally at `:4001`
-
-4 . client setup
-
 # @revertdotdev/client
 
+### Copy the example env file in `packages/client` folder.
+
 ```shell
-# Copy the example env file
-cp packages/client/.env.example packages/client/.env
 
-# Update this .env file with your own secrets if you'd like to.
+cp packages/client/.env.example packages/client/.env
+# Update this .env file with your own secrets if you'd like to.Clerk publishable key is must.
 ```
 
-1. Generate a Tunnel URL
+### Generate a Tunnel URL
 
 -   First, generate a tunnel URL using `ngrok http <4001 or YOUR_SERVER_PORT>`
+
 -   Copy this URL to your clipboard as you'll need it in the next steps.
 
-2. Configure Clerk Webhook Endpoint
+### Configure Clerk Webhook Endpoint
+
+-   Access your Clerk dashboard (Sign up on https://clerk.com/ if you have not already).
+
+-   Navigate to the webhook settings.
+
+-   Ensure that the webhook endpoint is set to
+    `<Tunnel_Url>/clerk/webhook`
 
--   Access your Clerk dashboard (Sign up on https://clerk.com/ if you have note already).
--   Navigate to the webhook settings or configuration section.
--   Ensure that the webhook endpoint is set to `<YOUR_LOCALHOST_OR_PUBLIC_URL>/clerk/webhook`
 -   Ensure that you are listening to the `user.created` event by ticking the `user`object under `Message Filtering`
 
 <img src="https://res.cloudinary.com/dfcnic8wq/image/upload/v1702896296/Revert/Docs/ioj7i0dj97dzcmgb95p2.png" />
 
-3. Sign Up in Your Application
+### Sign Up in Your Application
+
+-   Run `yarn dev:all` in the root of this repo(Your backend must be setup).
+
+-   Go to `localhost:3000` and sign up.
 
--   Use your application to sign up a new user. This action will trigger a user creation event.
--   In your Clerk dashboard, you should now see a `user.created` object associated with the newly signed-up user.
+-   In your Clerk webhook dashboard, click on your webhook endpoint,go to logs and filter by user.created and you will see a new user created.Enter inside it and copy the content.
 
-4. Testing with Postman
+### Testing Clerk Webhook with Postman
 
--   To verify that Clerk is sending user creation notifications to your endpoint, you can use Postman for testing.
+To verify that Clerk is sending user creation notifications to your endpoint, you can use Postman for testing.
 
 -   Open Postman and create a new request.