Skip to main content

Contribute

Introduction​

This guide gives the steps to make a new integration for Vantik.

Prerequisites​

Install this tool before you start

Step 1: Set up your environment​

  1. Go to the /app/integrations folder in your Vantik project: 
    cd /app/integrations
  2. Install the dependencies: 
    pnpm install

Step 2: Make the files for the integration​

  1. In the new folder, run this command: 
    pnpm generate
  2. Give the name of the integration when the command asks for it. The command then writes the handler.ts and spec.ts files for your integration.

Step 3: Write your integration​

A Vantik integration uses one event handler. That handler processes each type of event in one function. Your integration is therefore mostly the code that you write for these event types.

How to handle an event​

The run function is the entry point for each event of your integration. The event payload holds a type, and that type tells your integration what to do. Handle each type as below:

  • IntegrationSpec: return a specification in JSON. The specification gives the capabilities of your integration, the authentication details that it needs, and its configuration options.
  • IntegrationCreate: Vantik sends this event when a user gives the authentication details. Process the input of the user and make the integration. For example, save the settings and make the necessary connections.
  • IntegrationDelete: Vantik sends this event when a user deletes the integration account.

Example code​

This is an example of the run function:

async function run(eventPayload: IntegrationEventPayload) {
  switch (eventPayload.event) {
    case IntegrationPayloadEventType.IntegrationSpec:
      return spec();

    case IntegrationPayloadEventType.IntegrationCreate:
      return await integrationCreate(
        eventPayload.payload.userId,
        eventPayload.payload.workspaceId,
        eventPayload.payload.data,
      );

    default:
      return {
        message: `The event payload type is ${eventPayload.event}`,
      };
  }
}

Steps to write the code​

  1. Open the handler.ts and spec.ts files that the command made.
  2. Do each TODO in those files, and the integration is then complete.

If you have a question or a comment, tell the maintainers on GitHub: https://github.com/vantikhq/vantik/issues