Node.js SDK

Our Node.js SDK allows you to easily setup, build, test, and go live with Alloy Embedded. Our SDK allows you to interface with our backend REST APIs in a quick and easy manner.

In this guide, we'll take a look at how to use the Node.js SDK.

Installation

To get started, install alloy-node using npm as seen below:

npm install alloy-node --save

Or using yarn:

yarn add alloy-node

Usage

The package needs to be configured with your account's API key, which is available in the Alloy Dashboard under settings. You must supply the API key with each instantiation of the module.

JavaScript

const apiClient = new Embedded("MY_API_KEY...);

Creating a User

Similar to Unified API, in order to make API calls to Alloy Embedded, you must first create a user. To create a user in Embedded, call the User.createUser() method as seen below. You must pass a unique username.

JavaScript

let bodyData = {
  username: `sara456`,
};
let data = await apiClient.User.createUser(body);

Once you've created a user, you'll need to identify that user each time you make a call that requires a userId. Fortunately, the identify() method exists for this purpose.

Pass a userId to the identify() method as seen below:

JavaScript

await apiClient.identify("YOUR_USER_ID");

Obtain a workflowId

Before you can make API calls to Alloy Embedded, you will need to install a workflow using our frontend SDK. You can read more here.

Making requests to Alloy Embedded SDK

Once you have a workflowId, you can make requests

JavaScript

await apiClient.identify("YOUR_USER_ID");
let data = await apiClient.Workflows.list();

This call will return all workflows relevant to the specified user.

Note that the userId is stored temporarily so as long as the library is instantiated. Therefore, you can make subsequent invocations without needing to invoke identify each time. To clear out the currently identified user, invoke the clear method as seen below.

JavaScript

await apiClient.identify("YOUR_USER_ID");
await apiClient.clear();

SDK Methods

---

User Methods

The user methods make it easy to create, update, find, and delete users in Alloy Embedded.

Create a User

Verifies the functionality of creating a user through the createUser method. It sends a request to the server with a unique username, and upon success, the user ID is stored for subsequent tests.

JavaScript

let body = {
  username: `user123`,
};
const apiClient = new Embedded("YOUR_API_KEY");

await apiClient.User.createUser(body);

Update a User

Ensures the ability to update user details using the updateUser method. It first identifies the user by setting the user ID and then sends a request to update the user's full name.

JavaScript

const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify("userId");

let body = {
  fullName: `user123`,
};

await apiClient.User.updateUser(body);

Get a User

Checks the functionality of retrieving user information with the getUser method. After identifying the user, it sends a request to the server to get the user's details.

JavaScript

const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify("userId");

await apiClient.User.getUser();

List All Users

Verifies the ability to retrieve a list of all users, using the listUsers method after identifying the user. The server responds with a list of users, and the test ensures the expected properties are present.

JavaScript

const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify("userId");

await apiClient.User.listUsers();

Batch Create Users

Validates the batch creation of users through the createBatchUsers method. After identifying the user, it sends a request to the server with a batch of user data and expects a success message in response.

JavaScript

const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify("userId");

let batchData = {
  users: [
    { username: `user123`, fullName: "Joe Smoe" },
    { username: `user123` },
    { username: `user123`, fullName: "Jane Doe" },
  ],
};

await apiClient.User.createBatchUsers(batchData);

Delete a User

Verifies the functionality of deleting a user using the deleteUser method. After identifying the user, it sends a request to the server to delete the user account.

JavaScript

const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify("userId");

await apiClient.User.deleteUser();

Workflow Methods

List Workflows

Lists all workflows associated with the user.

JavaScript

let data = await apiClient.Workflows.list();

List Workflow Versions

Lists all versions of a specific workflow.

JavaScript

let data = await apiClient.Workflows.listVersions(workflowId);

Get Workflow Details

Gets details about a specific workflow.

JavaScript

let data = await apiClient.Workflows.get(workflowId);

Deactivate All Workflows

Deactivates all workflows associated with the user.

JavaScript

let data = await apiClient.Workflows.deactivateAll();

Activate Workflow

Activates a specific workflow.

JavaScript

let data = await apiClient.Workflows.activate(workflowId);

Deactivate Workflow

Deactivates a specific workflow.

JavaScript

let data = await apiClient.Workflows.deactivate(workflowId);

Upgrade Workflow

Upgrades a specific workflow to the latest version.

JavaScript

let data = await apiClient.Workflows.upgrade(workflowId);

Delete Workflow

Deletes a specific workflow.

JavaScript

let data = await apiClient.Workflows.delete(workflowId);

Tokens Methods

Get User Token

Generate a short lived user token (JSON Web Token) to pass to your fronent. This method is required in order to properly render the Alloy Modal on your frontend.

JavaScript

const apiClient = new Tokens("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.get();

Credentials Methods

Create Credential

Creates a new user credential.

JavaScript

const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify(userId);
let credential = {
  credential: {
    type: "wooCommerce",
    data: {
      consumerKey: "XXX",
      consumerSecret: "XXX",
      url: "XXX",
    },
  },
};
let data = await apiClient.Credentials.create(credential);

List User Credentials

Lists all credentials associated with the user.

JavaScript

const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.Credentials.listUserCredentials();

Get Metadata

Retrieves metadata for user credentials.

JavaScript

const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.Credentials.getMetadata();

Delete Credential

Deletes a specific user credential.

JavaScript

const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.Credentials.delete(credentialId);

Generate OAuth Link

Generates an OAuth link for a specific app and integration.

JavaScript

const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.Credentials.generateOauthLink(
  "shopify",
  "integrationId"
);

Logs Methods

Get Workflow Errors

Retrieve errors associated with a specific workflow.

JavaScript

const apiClient = new Logs("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.getWorkflowErrors();

Get Workflow Logs

Retrieve logs associated with a specific workflow.

JavaScript

const apiClient = new Logs("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.getWorkflowLogs();

Rerun Workflow Execution

Rerun a specific workflow execution.

JavaScript

const apiClient = new Logs("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.rerunWorkflowExecution();

Compliance Methods

Delete User Logs

Delete user logs for compliance purposes. Can be used in conjunction with a GDPR or CCPA request.

JavaScript

const apiClient = new Compliance("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.deleteUserLogs();

Link Methods

Generate Installation URL

Generate an external installation URL for a specific integration. This method is used for Embedded Link.

JavaScript

const apiClient = new Link("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.generate(integrationId);

Note: Make sure to create a user and list integrations before calling the generate method to ensure a valid userId and integrationId.

Integration Methods

List Integrations

Retrieves a list of integrations associated with the user.

JavaScript

const apiClient = new Integration("YOUR_API_KEY");
let data = await apiClient.listIntegrations();

Get Integration

Retrieves details about a specific integration.

JavaScript

const apiClient = new Integration("YOUR_API_KEY");
let integrationId = "your_integration_id"; // Replace with the actual integration ID
let data = await apiClient.getIntegration(integrationId);

Events Methods

List Events

Lists all events associated with the user.

JavaScript

const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.Events.list();

Run Event

Runs a specific event with optional data.

JavaScript

const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify(userId);
let eventName = "Get Customers";
let bodyData = { name: "Gregg" };
let data = await apiClient.Events.run(eventName, bodyData);

Apps Methods

Get Apps

Retrieves a list of available apps.

JavaScript

const apiClient = new App("YOUR_API_KEY");
let data = await apiClient.getApps();

Analytics Methods

Get Workflow Analytics

Retrieves analytics data for the specified workflow, based on the identified user.

JavaScript

const apiClient = new Analytics(apiKey);
await apiClient.identify(userId);
let data = await apiClient.get(workflowId);