Steps to implement a new provider
The backend logic:
- Define DTO for the settings of the provider
- Generate an authentication URL
- Authenticate the user from the callback
- Refresh the user token
The frontend logic:
- Implement the settings page
- Implement the preview page
- Upload the provider image
Social Media
Backend
For our example, we will use the X provider.
- First, we need to create a DTO for the settings of the provider.
head over tonestjs-libraries/src/dtos/posts/providers-settings
And create a new filex-provider-settings.dto.ts
(you don't have to create a DTO if there are no settings)
Once created head over tonestjs-libraries/src/dtos/posts/providers-settings/all.providers.settings.ts
And add the new DTO.
Head tolibraries/nestjs-libraries/src/dtos/posts/create.post.dto.ts
look for the discriminator and add another line in the format of
{ value: DTOClassName, name: 'providerName' },
- head over to
libraries/nestjs-libraries/src/integrations/social
And create a new provider fileproviderName.provider.ts
The content of the file should look like this:
For oAuth2 providers
import {
AuthTokenDetails,
PostDetails,
PostResponse,
SocialProvider,
} from '@gitroom/nestjs-libraries/integrations/social/social.integrations.interface';
export class XProvider implements SocialProvider {
identifier = 'providerName';
name = 'Provider Name';
async refreshToken(refreshToken: string): Promise<AuthTokenDetails> {
...refresh the token
}
async generateAuthUrl() {
...generate the auth url
}
async authenticate(params: { code: string; codeVerifier: string }) {
...authenticate the user
}
async post(
id: string,
accessToken: string,
postDetails: PostDetails<DTOClassName>[]
): Promise<PostResponse[]> {
...post the content
}
}
Take a look at the exising providers to see how to implement the methods.
Custom functions
You might want to create custom functions for the providers for example: get available orgs, get available pages, etc.
You can create a public function in the provider for example organizations
and later call it from a special hook from the frontend.
Integration Manager
Open libraries/nestjs-libraries/src/integrations/integration.manager.ts
And add the new provider to either socialIntegrationList
(oAuth2) or articleIntegrationList
(Token)
Frontend
- Head over to
apps/frontend/src/components/launches/providers
Create a new folder with the providerName
Add a new fileproviderName.provider.tsx
The content of the file should look like this:
import { FC } from 'react';
import { withProvider } from '@gitroom/frontend/components/launches/providers/high.order.provider';
import { useSettings } from '@gitroom/frontend/components/launches/helpers/use.values';
import { useIntegration } from '@gitroom/frontend/components/launches/helpers/use.integration';
const ProviderPreview: FC = () => {
const { value } = useIntegration();
const settings = useSettings();
return (
...Preview
);
};
const ProviderSettings: FC = () => {
const form = useSettings();
const { date } = useIntegration();
return (
...Settings
);
};
export default withProvider(DevtoSettings, DevtoPreview, DTOClassName);
If you want to use a custom function for the provider you can use the useCustomProviderFunction
hook.
import { useCustomProviderFunction } from '@gitroom/frontend/components/launches/helpers/use.custom.provider.function';
import { useCallback } from 'react';
const customFunc = useCustomProviderFunction();
// and use it like that:
const getOrgs = useCallback(() => {
customFunc.get('organizations', {
anyKey: 'anyValue'
})
}, []);
It will automatically interact with the right provider saved for the user.
You can look at the other integration to understand what data to put inside.
- Open
apps/frontend/src/components/launches/providers/show.all.providers.tsx
And add the new provider to the list.
{identifier: 'providerName', component: DefaultImportFromHighOrderProvider},