Add a network

A network is called a provider in the code. Adding one means a provider class on the backend, which signs in, refreshes tokens and publishes, and a component on the frontend for the network’s post settings and preview. Set up the development environment first. Read an existing provider that connects the way your network does before you start: OAuth (linkedin, pinterest), a key or login typed into the connect form (bluesky, devto), or the browser extension (skool). The imports below use @gitroom/*. That is the workspace alias in tsconfig.base.json, and it is correct.

Backend

Define the post settings

If posts to the network take settings, such as a title or a board, create a DTO with class-validator rules in libraries/nestjs-libraries/src/dtos/posts/providers-settings/<name>.dto.ts.Then register it in all.providers.settings.ts in the same folder, twice: a ProviderExtension<'your-identifier', YourDto> member of the AllProvidersSettings type, and a line in the list allProviders() returns:

{ value: YourDto, name: 'your-identifier' },

A network without settings still needs both: a ProviderExtension<'your-identifier', None> member of the type, and a list line with setEmpty as the value, the way threads and bluesky have them. The create-post DTO checks each post’s __type against this list and refuses any identifier that is missing.

Write the provider

Create libraries/nestjs-libraries/src/integrations/social/<name>.provider.ts. A provider extends SocialAbstract, which supplies shared helpers such as an SSRF-guarded fetch and default checkValidity, checkPostStatus and finalizePost, and implements SocialProvider:

import {
  AuthTokenDetails,
  PostDetails,
  PostResponse,
  SocialProvider,
} from '@gitroom/nestjs-libraries/integrations/social/social.integrations.interface';
import { SocialAbstract } from '@gitroom/nestjs-libraries/integrations/social.abstract';
import { YourDto } from '@gitroom/nestjs-libraries/dtos/posts/providers-settings/your.dto';

export class YourProvider extends SocialAbstract implements SocialProvider {
  identifier = 'your-identifier';
  name = 'Your Network';
  isBetweenSteps = false;
  scopes = ['scope.a', 'scope.b'];
  editor = 'normal' as const; // 'none' | 'normal' | 'markdown' | 'html'
  category = 'social' as const; // its group on the Add Channel screen
  dto = YourDto;

  maxLength() {
    return 5000;
  }

  async generateAuthUrl() {
    // return { url, codeVerifier, state }
  }

  async authenticate(params: { code: string; codeVerifier: string }) {
    // exchange the code, return AuthTokenDetails
  }

  async refreshToken(refreshToken: string): Promise<AuthTokenDetails> {
    // return fresh AuthTokenDetails
  }

  async post(
    id: string,
    accessToken: string,
    postDetails: PostDetails<YourDto>[]
  ): Promise<PostResponse[]> {
    // publish, and return one PostResponse per entry
  }
}

Override checkValidity to refuse, before a post is scheduled, what the network’s API would reject: media count, formats, lengths.
A network that takes a key or a login instead of OAuth implements customFields(), and the connect form asks for those fields.
Keep network-specific logic in the provider. Generic code calls the provider through the interface and never tests which network it is.

Add an instance to socialIntegrationList in libraries/nestjs-libraries/src/integrations/integration.manager.ts. That list is what Add Channel offers, and where the workers get their per-network queues.

Extra functions

A provider can expose more functions, for example one that lists the pages or boards the account can post to. Add a public async method to the class. It receives the channel’s token, the data the frontend sent, the channel’s internal id and the channel:

async boards(token: string, data: any, internalId: string) {
  // return the list
}

Decorate it with @Tool({ description, dataSchema }) from @gitroom/nestjs-libraries/integrations/tool.decorator if AI agents should be able to call it too.

Frontend

Write the settings component

Create apps/frontend/src/components/new-launch/providers/<name>/<name>.provider.tsx:

'use client';

import { FC } from 'react';
import { withProvider } from '@gitroom/frontend/components/new-launch/providers/high.order.provider';
import { PostComment } from '@gitroom/frontend/components/new-launch/providers/post-comment.enum';
import { useSettings } from '@gitroom/frontend/components/launches/helpers/use.values';
import { YourDto } from '@gitroom/nestjs-libraries/dtos/posts/providers-settings/your.dto';

const YourSettings: FC = () => {
  const { register } = useSettings();
  return <input {...register('title')} />;
};

export default withProvider({
  postComment: PostComment.COMMENT,
  minimumCharacters: [],
  SettingsComponent: YourSettings,
  CustomPreviewComponent: undefined,
  dto: YourDto,
  maximumCharacters: 5000,
});

Pass SettingsComponent: null for a network without settings.

Call an extra function, if you added one

import { useCallback } from 'react';
import { useCustomProviderFunction } from '@gitroom/frontend/components/launches/helpers/use.custom.provider.function';

const customFunc = useCustomProviderFunction();
const loadBoards = useCallback(() => customFunc.get('boards', {}), [customFunc]);

The hook posts to the backend’s /integrations/function route for the channel being edited.

In apps/frontend/src/components/new-launch/providers/show.all.providers.tsx, import it and add it to Providers:

{ identifier: 'your-identifier', component: YourProvider },

Add the icon

Save the network’s icon as apps/frontend/public/icons/platforms/<identifier>.png.

Before you open a pull request

Connect a test account, publish a post with and without media, and check that checkValidity refuses what the network refuses.
Add the network’s variables, if any, to .env.example.
Run pnpm run lint from the repository root and pnpm test.

The contributing guide has the pull request template.

Start here

Install

Domain and HTTPS

Configure

Channel developer apps

Operate

Develop

Backend

Extra functions

Frontend

Before you open a pull request

​Backend

​Extra functions

​Frontend

​Before you open a pull request

​Related

Backend

Extra functions

Frontend

Before you open a pull request

Related