@elasticpath/ih-automation

ih-automation

This package provides:

• An abstraction of the Elastic Path Composable Commerce and Elastic Path Composer APIs that are required to automate common Integrations Hub tasks, such as CRUD operations on integration instances.
• APIs that can be used to quickly build integration instance import/export processes that can be used within pipelines.
• APIs that can be used to navigate or create stores within an EPCC organization.

Installation

Use the following commands to install this package.

yarn install @elasticpath/ih-automation

.env file

The following environment variables need to be set for this package to be able to access your Elastic Path environment. These are usually set in a locally maintained .env file in the repository root and the dotenv package is used to inject the variables from .env into the Node runtime.

EPCC_CLIENT_ID={replace with the client id of your EPCC application key}
EPCC_CLIENT_SECRET={replace with the client secret of your EPCC application key}
EPCC_API_DOMAIN={useast.api.elasticpath.com or euwest.api.elasticpath.com}
EPCC_INTEGRATIONS_HUB_API_DOMAIN={us-east-2.elasticpathintegrations.com or eu-west-1.elasticpathintegrations.com}
DEFAULT_LOG_LEVEL={error or warn or info or debug or trace}

Usage

The following code examples demonstrate how to perform some of the most common tasks.

Export Integration Instances and Configurations

This example saves the exported instances and their configurations to a JSON file.

import dotenv from "dotenv";
dotenv.config({ path: ".env" });
import * as epccIHAutomation from "@elasticpath/ih-automation";
import fs from "fs";

async function exportAllInstanceConfigurationsToJson() {
  const instances = await epccIHAutomation .exportCustomerInstances();
  const formattedInstanceConfigs = {
    ihIntegrations: instances.map((instance) => ({
      integrationName: instance.integration.name,
      instanceName: instance.instance.name,
      instanceDescription: instance.instance.description,
      configVariables: instance.configVariables,
      flowConfigs: instance.flowConfigs,
    })),
  };
  fs.writeFileSync("instance-export.json", JSON.stringify(formattedInstanceConfigs, null, 2));
}

exportAllInstanceConfigurationsToJson();

Upsert Integration Instances and Configurations

This example upserts the integration instances and their configurations from the JSON file that was generated in the previous example.

import dotenv from "dotenv";
dotenv.config({ path: ".env" });
import { upsertIntegrationInstance, InstanceDetail } from "@elasticpath/ih-automation";
import fs from "fs";

async function importIntegrationsFromFile(filename: string) {
  let instanceDetails: InstanceDetail[];
  try {
    const instanceDetailsFromFile = fs.readFileSync(filename, { encoding: "utf-8" });
    const instances = JSON.parse(instanceDetailsFromFile);
    instanceDetails = instances.ihIntegrations;
  } catch (error) {
    console.error("Could not parse JSON file: ", error);
    throw error;
  }
  if (instanceDetails) {
    try {
      for (const instanceDetail of instanceDetails) {
        await upsertIntegrationInstance(instanceDetail);
      }
    } catch (error) {
      console.error("Could not upsert integration instance", error);
      throw error;
    }
  }
}

importIntegrationsFromFile("output/instance-export.json");

Upgrade an Integration Instance to the Latest Available Version

Note that customers are not allowed to change integration instances to specific versions. Instances can only be created and updated to the latest available version. If you feel you need to specify a different version, please contact the Elastic Path Support Team.

import * as dotenv from "dotenv";
dotenv.config({ path: ".env" });
import { upgradeIntegrationInstanceByName } from "@elasticpath/ih-automation";

await upgradeIntegrationInstanceByName("SendGrid Email", true);

API Documentation

Store Management Functions

createStore(store: EPCCStore): Promise<CreateStoreResponse>

Creates a new EPCC store. Requires an Organization-level Application Key for authorization.

• Parameters:
  • store: EPCCStore object containing store details
• Returns: Promise resolving to the created store response

getStores(): Promise<OrganizationStore[]>

Fetches all stores for the organization. Requires an Organization-level Application Key for authorization.

• Returns: Promise resolving to an array of organization stores

switchSessionToOrg(orgId: string): Promise<SwitchStoreResponse>

Switches the current session to a specified organization. Requires an Organization-level Application Key for authorization.

• Parameters:
  • orgId: The ID of the organization to switch to
• Returns: Promise resolving with the switch response

switchStoreInOrg(storeId: string): Promise<SwitchStoreResponse>

Switches to a specific store within the current organization. Requires an Organization-level Application Key for authorization.

• Parameters:
  • storeId: The ID of the store to switch to
• Returns: Promise resolving with the switch response

Authentication Functions

getJWT(): Promise<string>

Fetches the EPCC JWT token for authentication.

• Returns: Promise resolving with the JWT token

integrationHubAuthenticate(jwt: string): Promise<void>

Authenticates with the Integrations Hub using a JWT token.

• Parameters:
  • jwt: The JWT token for authentication
• Returns: Promise resolving when authentication is complete

Integration Hub Functions

getIHCustomerId(): Promise<string>

Retrieves the Integrations Hub Customer ID for the authenticated user.

• Returns: Promise resolving with the customer ID
• Throws: Error if not authenticated with integrationHubAuthenticate first

getCurrentIntegrationIdByName(name: string): Promise<GetIntegrationResponse>

Retrieves the current integration ID by its name.

• Parameters:
  • name: The name of the integration
• Returns: Promise resolving with the integration details
• Throws: Error if not authenticated with integrationHubAuthenticate first

getIntegrationInstanceByName(name: string): Promise<GetInstanceResponse>

Retrieves an integration instance by its name.

• Parameters:
  • name: The name of the integration instance
• Returns: Promise resolving with the instance details
• Throws: Error if not authenticated with integrationHubAuthenticate first

createIntegrationInstance(ihCustomerId: string, instanceDetails: InstanceDetail, flowConfigs?: InputFlowConfig[]): Promise<CreateInstanceResponse>

Creates a new integration instance.

• Parameters:
  • ihCustomerId: The Integrations Hub customer ID
  • instanceDetails: Details of the instance to create
  • flowConfigs: Optional flow configurations
• Returns: Promise resolving with the created instance details
• Throws: Error if not authenticated with integrationHubAuthenticate first

updateIntegrationInstanceConfiguration(instanceDetails: InstanceDetail, flowConfigs?: InputFlowConfig[]): Promise<UpdateInstanceResponse>

Updates an existing integration instance configuration.

• Parameters:
  • instanceDetails: Details of the instance to update
  • flowConfigs: Optional flow configurations
• Returns: Promise resolving with the update response
• Throws: Error if not authenticated with integrationHubAuthenticate first

deployIntegrationInstance(instanceId: string): Promise<string>

Deploys an integration instance.

• Parameters:
  • instanceId: The ID of the instance to deploy
• Returns: Promise resolving with the configuration state
• Throws: Error if not authenticated with integrationHubAuthenticate first

upgradeIntegrationInstanceByName(instanceName: string, deployNewInstance = true): Promise<void>

Upgrades an integration instance to the latest version. Please note that this process will only work properly if the configuration variables in the new version are backward compatible with the current version. This does not modify the config variables for the instance in any way.

• Parameters:
  • instanceName: The name of the instance to upgrade
  • deployNewInstance: Whether to deploy the new instance after upgrade (default: true)
• Returns: Promise resolving when the upgrade is complete
• Throws: Error if instance is not found or if upgrade fails

getCustomerInstances(ihCustomerId: string): Promise<InstancesResponse[]>

Retrieves all instances for a customer (limited to first 100).

• Parameters:
  • ihCustomerId: The Integrations Hub customer ID
• Returns: Promise resolving with the customer instances
• Throws: Error if not authenticated with integrationHubAuthenticate first

exportCustomerInstances(): Promise<InstancesResponse[]>

Exports all customer integration instances.

• Returns: Promise resolving with all customer instances

upsertIntegrationInstance(...instanceDetails: InstanceDetail[]): Promise<InstanceDetail[]>

Creates or updates integration instances.

• Parameters:
  • instanceDetails: The instance details to create or update (spread parameter)
• Returns: Promise resolving with the updated instance details

authorizeConnections(authorizeUrls: string[]): Promise<void>

Authorizes connections using provided authorization URLs.

• Parameters:
  • authorizeUrls: Array of URLs to authorize
• Returns: Promise resolving when all authorizations are complete

User Management Functions

inviteUsers(storeId: string, users: string[]): Promise<InviteUsersResponse>

Invites users to a store with seller-admin role.

• Parameters:
  • storeId: The ID of the store to invite users to
  • users: Array of user emails to invite
• Returns: Promise resolving with the invite response