How to add a new provider

Adding a network she can post to means writing code in two places: a provider on the backend that knows how to authenticate and publish, and a pair of components on the frontend for the preview and the per-network settings.

About the @gitroom/* import paths below. They are correct and deliberate. That is the real workspace alias in tsconfig.base.json, inherited from the upstream project, and renaming it would break every import in the monorepo. Only the product is called PostQueen.

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

Backend

For our example, we will use the X provider.

Create a DTO for provider settings

Head over to libraries/nestjs-libraries/src/dtos/posts/providers-settings and create a new file x-provider-settings.dto.ts

You do not have to create a DTO if there are no settings

Once created head over to libraries/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, where the value is your DTO class and the name matches the provider’s identifier:

{ value: XProviderSettingsDto, name: 'x' },

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<XProviderSettingsDto>[]
  ): Promise<PostResponse[]> {
    // ...post the content
  }
}

Take a look at the existing providers to see how to implement the methods.

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

Create provider component

Head over to apps/frontend/src/components/new-launch/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/new-launch/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
  );
};

// The third argument is the settings DTO class you created on the backend,
// for example ProviderNameSettingsDto.
export default withProvider(ProviderSettings, ProviderPreview, ProviderNameSettingsDto);

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.

Open apps/frontend/src/components/launches/providers/show.all.providers.tsx and add the new provider to the list.

{identifier: 'providerName', component: DefaultImportFromHighOrderProvider},

Start here

Install

Domain and HTTPS

Configuration

Connect your channels

Operations

Other install methods

Extend PostQueen

Steps to implement a new provider

Backend

Custom functions

Frontend

​Steps to implement a new provider

​Social Media

​Backend

​Custom functions

​Frontend

Steps to implement a new provider

Social Media

Backend

Custom functions

Frontend