Flex Plugins API Toolkit

A wrapper for performing the most common use cases of the Flex Plugins API.

Installation

Install this package using:

# Using npm
npm i -S flex-plugins-api-toolkit

# Using yarn
yarn add flex-plugins-api-toolkit

Usage

Instantiate a FlexPluginsAPIToolkit client by providing username/password (AccountSid/AuthToken, API Key/Secret, or JWE token).

import FlexPluginsAPIToolkit from 'flex-plugins-api-toolkit';

// Instantiate the HTTP client
const toolkit = new FlexPluginsAPIToolkit(process.env.USERNAME, process.env.PASSWORD);

// In case of a JWE token, the username is "token" and the password is your JWE token.

Methods

The toolkit provides the following commands.

Note: If you are using the JWE token for authentication, then all identifiers (such as name, version, etc) must be the sid of the resource only.

.deploy(option: DeployOption): Promise<DeployPlugin>

This command deploys a new plugin version to Plugins API. This wrapper upserts a plugin (i.e., updates the plugin if it exists, otherwise creates a new plugin) and then creates a new version.

The command takes an argument object of the format:

interface DeployOption {
  name: string;
  url: string;
  version: string;
  friendlyName?: string;
  description?: string;
  changelog?: string;
  isPrivate?: boolean;
}

The command returns a promise of type:

interface DeployPlugin {
  pluginSid: string;
  pluginVersionSid: string;
  name: string;
  version: string;
  url: string;
  friendlyName: string;
  description: string;
  changelog: string;
  isPrivate: boolean;
}

.createConfiguration(option: CreateConfigurationOption): Promise<CreateConfiguration>

This command creates a new configuration and installs a list of provided plugins.

The command takes an argument object of the format:

interface CreateConfigurationOption {
  addPlugins: string[];
  removePlugins?: string[];
  description?: string;
  fromConfiguration?: 'active' | string;
}

where the addPlugins field is an array of plugins formatted as pluginName@version. It is the list of plugins, and their corresponding versions that you want to include in this plugin (you can use Sids or unique name/version):

const option = {
  addPlugins: [
    'plugin-sample@1.0.0',
    'FPxxx@1.0.0',
    'another-plugin@FVxxx',
    'FPxxy@FVxxy'
  ],
  ...
}

The option removePlugins is useful when you want to create a new configuration from an existing configuration but then remove some plugins. This parameter is an array of plugin names only:

const option = {
  addPlugins: [
    'plugin-sample@1.0.0',
    'FPxxx@1.0.0',
    'another-plugin@FVxxx',
    'FPxxy@FVxxy'
  ],
  removePlugins: ['pluginName'],
  ...
}

The command returns a promise of type:

export interface CreateConfiguration {
  configurationSid: string;
  name: string;
  description: string;
  dateCreated: string;
  plugins: Array<{
    pluginSid: string;
    pluginVersionSid: string;
    name: string;
    version: string;
    url: string;
    friendlyName: string;
    description: string;
    changelog: string;
    isPrivate: boolean;
    phase: number;
  }>;
}

.release(option: ReleaseOption): Promise<Release>

This command creates a new release and activates the given configuration.

The command takes an argument object of the format:

interface ReleaseOption {
  configurationSid: string;
}

The command returns a promise of type:

interface Release {
  releaseSid: string;
  configurationSid: string;
  dateCreated: string;
}

.describePlugin(option: DescribePluginOption): Promise<DescribePlugin>

This command returns information about a plugin and its versions.

The command takes an argument object of the format:

interface DescribePluginOption {
  name: string;
}

where the name is either the plugin's unique name or its sid.

The command returns a promise of type:

interface DescribePlugin {
  sid: string;
  name: string;
  friendlyName: string;
  description: string;
  isActive: boolean;
  dateCreated: string;
  dateUpdated: string;
  versions: Array<{
    sid: string;
    version: string;
    url: string;
    changelog: string;
    isPrivate: boolean;
    isActive: boolean;
    dateCreated: string;
  }>;
}

The field isActive is set to true if this plugin is part of an active release. The associated version that is part of the active release also has isActive set to true.

.describePluginVersion(option: DescribePluginVersionOption): Promise<DescribePluginVersion>

This command returns information about a plugin version.

The command takes an argument object of the format:

interface DescribePluginVersionOption {
  name: string;
  version: string;
}

where the name is either the plugin's unique name or its sid; the version is either the plugin version's version or its sid.

The command returns a promise of type:

interface DescribePluginVersion {
  sid: string;
  version: string;
  url: string;
  changelog: string;
  isPrivate: boolean;
  isActive: boolean;
  plugin: {
    sid: string;
    name: string;
    friendlyName: string;
    description: string;
    dateCreated: string;
    dateUpdated: string;
  };
  dateCreated: string;
}

The field isActive is set to true if this plugin version is part of an active release.

.describeConfiguration(option: DescribeConfigurationOption): Promise<DescribeConfiguration>

This command returns information about a configuration, including a list of plugins included in it.

The command takes an argument object of the format:

interface DescribeConfigurationOption {
  sid: string;
}

The command returns a promise of type:

interface DescribeConfiguration {
  sid: string;
  name: string;
  description: string;
  isActive: boolean;
  dateCreated: string;
  plugins: Array<{
    pluginSid: string;
    pluginVersionSid: string;
    name: string;
    version: string;
    url: string;
    friendlyName: string;
    description: string;
    changelog: string;
    isPrivate: boolean;
    phase: number;
  }>;
}

The field isActive is set to true if this configuration is part of an active release.

.describeRelease(option: DescribeReleaseOption): Promise<Release>

This command returns information about a release.

The command takes an argument object of the format:

interface DescribeReleaseOption {
  sid: string;
}

The command returns a promise of type:

interface Release {
  sid: string;
  configurationSid: string;
  isActive: boolean;
  dateCreated: string;
  configuration: {
    sid: string;
    name: string;
    description: string;
    isActive: boolean;
    dateCreated: string;
    plugins: Array<{
      pluginSid: string;
      pluginVersionSid: string;
      name: string;
      version: string;
      url: string;
      friendlyName: string;
      description: string;
      changelog: string;
      isPrivate: boolean;
      phase: number;
   }>;
  }
}

The field isActive is set to true if this release is the active release.

.listPlugins(option: ListPluginsOption): Promise<ListPluginsResource>

This command returns a list of plugins.

The command takes an argument object of the format:

interface ListPluginsOption {
  page?: Pagination;
}

The command returns a promise of type:

interface ListPluginsResource {
  plugins: Array<{
    sid: string;
    name: string;
    friendlyName: string;
    description: string;
    isActive: boolean;
    dateCreated: string;
    dateUpdated: string;
  }>;
  meta: PaginationMeta;
}

The field isActive is set to true if this plugin is part of an active release.

.listPluginVersions(option: ListPluginVersionsOption): Promise<ListPluginVersionsResource>

This command returns a list of plugins.

The command takes an argument object of the format:

interface ListPluginVersionsOption {
  name: string;
  page?: Pagination;
}

The command returns a promise of type:

interface ListPluginVersionsResource {
  plugin_versions: Array<{
    sid: string;
    pluginSid: string;
    version: string;
    url: string;
    changelog: string;
    isPrivate: boolean;
    isActive: boolean;
    dateCreated: string;  
  }>;
  meta: PaginationMeta;
}

The field isActive is set to true if this plugin version is part of an active release.

.listConfigurations(option: ListConfigurationsOption): Promise<ListConfigurationsResource>

This command returns a list of plugins.

The command takes an argument object of the format:

interface ListConfigurationsOption {
  page?: Pagination;
}

The command returns a promise of type:

interface ListConfigurationsResource {
  plugins: Array<{
    sid: string;
    name: string;
    description: string;
    isActive: boolean;
    dateCreated: string;
  }>;
  meta: PaginationMeta;
}

The field isActive is set to true if this configuration is part of an active release.

.listReleases(option: ListReleasesOption): Promise<ListReleasesResource>

This command returns a list of plugins.

The command takes an argument object of the format:

interface ListReleasesOption {
  page?: Pagination;
}

The command returns a promise of type:

interface ListReleasesResource {
  plugins: Array<{
    sid: string;
    configurationSid: string;
    dateCreated: string;
  }>;
  meta: PaginationMeta;
}

.diff(option: DiffOption): Promise<Diff>

This commands returns a diff of two configurations.

The command takes an argument object of the format:

export interface DiffOption {
  resource: 'configuration';
  oldIdentifier: string;
  newIdentifier: string;
}

where oldIdentifier/newIdentifier can either be a ConfigurationSid or the string active. If active is returned, the script finds the ConfigurationSid corresponding to the active Configuration.

The command returns a promise of type:

interface Difference<T> {
  path: keyof T;
  hasDiff: boolean;
  before: unknown;
  after: unknown;
}

interface ConfigurationsDiff {
  configuration: Difference<Omit<DescribeConfiguration, 'plugins'>>[];
  plugins: {
    [key: string]: Difference<ConfiguredPlugins>[];
  };
}
type Diff = ConfigurationsDiff;

Shared Types

The Pagination interface is:

interface Pagination {
  pageSize?: number;
  page?: number;
  pageToken?: string;
}

The PaginationMeta interface is:

interface PaginationMeta {
  meta: {
    page: number;
    page_size: number;
    first_page_url: string;
    previous_page_url: string;
    url: string;
    next_page_url?: string;
    key: string;
    next_token?: string;
    previous_token?: string;
  };
}

where next_token and previous_token are extracted PageToken query parameter from the next_page_url and previous_page_url parameter respectively.

Tools

This package also exposes the following tools:

findConfigurationsDiff(oldConfiguration: DescribeConfiguration, newConfiguration: DescribeConfiguration): ConfigurationsDiff

This tool compares two DescribeConfiguration and returns the diff between the two.