Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update CONTRIBUTING.md #510

Merged
merged 2 commits into from
Mar 7, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 1 addition & 29 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,32 +45,4 @@ yarn build

## Contributing an API Integration

**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.

**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.

**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`.

> Note: 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:** 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:** 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`.

**Unification Process:** Performed while retrieving resources from third party to match the provided schema. The process involves the following steps:

1. Request to Third-Party Endpoint: Begin by initiating a request to the third-party endpoint.
2. unifyObject: After receiving the response, pass it to `unifyObject`, incorporating a preprocessing to standardize essential values.
3. transformFieldMappingToModel: Send the preprocessed data to `transformFieldMappingToModel`, which aligns it with the provided schema.
4. Unified Response: The processed data is returned as a unified response.

**Disunification Process:** Primarily performed during the creation or updating of a resource. When a create or update request is made, it is initially in the format defined by Revert. This format is then disunified to align with the structure accepted by the third party. The process involves the following steps:

1. `disunifyObject`: The initial Revert-defined format is disunified.
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.
See https://docs.revert.dev/overview/developer-guide/contribute-an-api-integration for more on how to contribute an integration.
Loading