@chec/integration-configuration-sdk

Integration Configuration App SDK

This SDK is available to help build custom configuration apps for integrations that work with Commerce.js infrastructure and appear within the Chec Dashboard.

Installation

yarn add @chec/integration-configuration-sdk

Usage

There are two options for controlling the configuration of an integration. You can either choose to create a completely custom web app that will appear within the Chec Dashboard (the "frame" option), or you can dynamically update the form schema of the integration template, and react to input and events triggered by the user (the "controlled" option).

Establishing a connection to the Chec Dashboard

As your app will be brought in and shown during a user session in the Chec Dashboard, the app will need to establish a connection to the dashboard:

import { createSDK, ConfigSDK } from '@chec/integration-configuration-sdk';

createSDK().then((sdk: ConfigSDK) => {
  // Typescript is shown, but you can remove the references to `ConfigSDK` to convert to native JS
})

Next, you will need to decide how you will influence the configuration screen by choosing one of the options detailed above.

"Controlled" option

This option does not require your app to product any user interface. Instead, you can use the SDK to update the form schema that the Chec Dashboard uses to display a form:

import { createSDK, SchemaFieldTypes } from '@chec/integration-configuration-sdk';

(async () => {
  const sdk = await createSDK();

  sdk.setSchema([
    {
      key: 'name',
      type: SchemaFieldTypes.ShortText,
      label: 'Your name',
    },
  ]);
})();

When the configuration screen renders in the Chec Dashboard, a form will display that matches the schema set by your app. As the user fills in the form, the integration config is updated as usual.

Watching for events

You can register an event handler that is called when the configuration changes:

import { createSDK } from '@chec/integration-configuration-sdk';

(async () => {
  const sdk = await createSDK();

  sdk.onConfigUpdate((config: object) => {
    console.log(config);
  });
})();

You can render buttons and watch for clicks:

import { createSDK, SchemaFieldTypes } from '@chec/integration-configuration-sdk';

(async () => {
  const sdk = await createSDK();

  sdk.setSchema([
    {
      key: 'my_button',
      type: SchemaFieldTypes.Button,
      label: 'Click me',
    },
  ]);

  sdk.on('click', 'my_button', () => {
    console.log('Clicked!');
  });
})();

You can also set config attributes directly using setConfig. Configuration set this way is merged with existing configuration.

import { createSDK } from '@chec/integration-configuration-sdk';

(async () => {
  const sdk = await createSDK();

  sdk.setConfig({
    my_custom_option: 'Hello world!',
  });
})();

Using typescript to ensure form schema matches configuration

This SDK provides types for form schema to help create valid form schemas for the Chec Dashboard. Additionally, you can provide a type definition for your configuration to perform type checking on the schema to ensure it matches the configuration you're expecting. For example, say you want to configure your integration with the following config:

export default interface MyIntegrationConfiguration {
  customerMessage: string
}

You may choose to create this in it's own file at the root of the project so it can be shared by the configuration app and the integration, that will have access to the config with (await context.integration()).config.

Then you can create a schema like so:

import { Schema, SchemaFieldTypes } from '@chec/integration-configuration-sdk';
import MyIntegrationConfiguration from '../config';

const schema: Schema<MyIntegrationConfiguration> = [
  {
    key: 'customerMessage',
    label: 'Message to display to the customer',
    type: SchemaFieldTypes.ShortText,
  }
];

Typescript with throw an error if the value for key does not exist in your configuration interface, avoiding potential typos and mistakes. Additionally, you can ensure the schema matches your configuration only when you set it:

import { createSDK } from '@chec/integration-configuration-sdk';
import MyIntegrationConfiguration from '../config';

(async () => {
  const sdk = await createSDK<MyIntegrationConfiguration>();

  sdk.setSchema([
    {
      key: 'customerMessage',
      label: 'Message to display to the customer',
      type: SchemaFieldTypes.ShortText,
    }
  ]);
})();

"Frame" option

You can build a custom UI to configure your app, and set the resulting configuration using the sdk.setConfig API detailed above. The Chec dashboard will render your app in the configuration panel, even when using the "controlled" option, but your app is hidden until the dashboard knows the height of the content that your app renders. You can report the height of your app using the SDK, or turn on the automatic height detection system:

(async () => {
  document.body.innerText = 'Hello world!';

  const sdk = await createSDK();

  sdk.setHeight(20); // In pixels
  // OR
  sdk.enableAutoResize();
})();

The UI library used by the Chec dashboard is open source and available for use by your app if you're building with Vue:

https://github.com/chec/ui-library - Storybook (demo site)