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.
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.
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:
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
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.
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.
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.
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.
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.
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.
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.
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.
let data = await apiClient.Workflows.list();
List Workflow Versions
Lists all versions of a specific workflow.
let data = await apiClient.Workflows.listVersions(workflowId);
Get Workflow Details
Gets details about a specific workflow.
let data = await apiClient.Workflows.get(workflowId);
Deactivate All Workflows
Deactivates all workflows associated with the user.
let data = await apiClient.Workflows.deactivateAll();
Activate Workflow
Activates a specific workflow.
let data = await apiClient.Workflows.activate(workflowId);
Deactivate Workflow
Deactivates a specific workflow.
let data = await apiClient.Workflows.deactivate(workflowId);
Upgrade Workflow
Upgrades a specific workflow to the latest version.
let data = await apiClient.Workflows.upgrade(workflowId);
Delete Workflow
Deletes a specific workflow.
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.
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.
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.
const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.Credentials.listUserCredentials();
Get Metadata
Retrieves metadata for user credentials.
const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.Credentials.getMetadata();
Delete Credential
Deletes a specific user credential.
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.
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.
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.
const apiClient = new Logs("YOUR_API_KEY");
await apiClient.identify(userId);
let data = await apiClient.getWorkflowLogs();
Rerun Workflow Execution
Rerun a specific workflow execution.
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.
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.
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.
const apiClient = new Integration("YOUR_API_KEY");
let data = await apiClient.listIntegrations();
Get Integration
Retrieves details about a specific integration.
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.
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.
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.
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.
const apiClient = new Analytics(apiKey);
await apiClient.identify(userId);
let data = await apiClient.get(workflowId);