Skip to main content

​
Steps to implement a new provider

  1. 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
  2. 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.
1

Create a DTO for provider settings

Head over to nestjs-libraries/src/dtos/posts/providers-settings and create a new file x-provider-settings.dto.ts
You don’t have to create a DTO if there are no settings
Once created head over to nestjs-libraries/src/dtos/posts/providers-settings/all.providers.settings.ts and add the new DTO.Head to libraries/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' },
2

Create the provider file

Head over to libraries/nestjs-libraries/src/integrations/social and create a new provider file providerName.provider.tsFor oAuth2 providers, the content of the file should look like this:
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 existing providers to see how to implement the methods.
3

Register with Integration Manager

Open libraries/nestjs-libraries/src/integrations/integration.manager.ts and add the new provider to either socialIntegrationList (oAuth2) or articleIntegrationList (Token)

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

​
Frontend

1

Create provider component

Head over to apps/frontend/src/components/launches/providers and create a new folder with the providerName.Add a new file providerName.provider.tsx with the following content:
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);
2

Use custom provider functions (optional)

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 integrations to understand what data to put inside.
3

Register the provider

Open apps/frontend/src/components/launches/providers/show.all.providers.tsx and add the new provider to the list.
{identifier: 'providerName', component: DefaultImportFromHighOrderProvider},