alloy-frontend/README.md

Front End SDK of Alloy Automation

# Alloy Automation Front End Library

The Alloy Automation Front End library provides convenient access to the pre-built modal, which allows easy access to use and embedded Alloy Automation's power into a frontend app.

## Requirements

Node 12 or higher.

## Installation

Install the package with:

```sh
npm install alloy-frontend
# or
yarn add alloy-frontend
```

# Usage

## Overview

The Alloy Frontend Library provides a set of functions for integrating with the Alloy platform, allowing users to install, authenticate, edit, update, and perform other operations related to workflows and integrations.

## Installation

To use the Alloy JavaScript Library, include the library in your project and instantiate the `Alloy` object.

```javascript
const Alloy = require('alloy-frontend');

const alloy = Alloy();
```

## Setup

To use this library, you must pass over a short lived JSON Web Token generated on your backend with the User Token API. If you are using Alloy Embedded you can find that endpoint [here](https://docs.runalloy.com/reference/generate-jwt-token).

Once you have the token, call the `setToken` method below.


### `setToken(token)`

Sets the authentication token for subsequent Alloy API requests.

- `token`: The JWT token to be set.

## Aloy Embedded Methods

### `install(params)`

Installs an Alloy integration or workflow. 

**Note: this method should ONLY be used for rendering the Alloy Embedded Modal.**

- `params`: An object containing installation parameters.
  - `integrationId`: The ID of the integration to be installed.
  - `workflowIds`: An array of workflow IDs to be installed.
  - `callback`: A callback function to be executed after installation.
  - `alwaysShowAuthentication`: Boolean indicating whether to always show authentication during installation.
  - `hide`: Boolean indicating whether to hide the installation modal.
  - `title`: The title to be displayed in the installation modal.
  - `operation`: The operation to be performed during installation (e.g., "edit" or "update").
  - `versionIds`: An array of version IDs for installation.

### `edit(params)`

Edits an Alloy workflow with additional parameters for customization.

- `params`: An object containing edit parameters.
  - Inherits parameters from the `install` function.

### `update(params)`

Updates an Alloy integration or workflow.

- `params`: An object containing update parameters.
  - Inherits parameters from the `install` function.


### `getWorkflows()`

Retrieves a list of workflows associated with the authenticated user.

### `getIntegrations()`

Retrieves a list of integrations associated with the authenticated user.

### `deactivate(data)`

Deactivates a workflow specified by the provided data.

- `data`: An object containing deactivation data.

### `reactivate(data)`

Reactivates a workflow specified by the provided data.

- `data`: An object containing reactivation data.


## Alloy Unified API Methods

### `authenticate(params)`

This method is used to render the Alloy Modal for use in Unified API.

**Note: this method should ONLY be used for rendering the Alloy Unified API Modal.**

- `params`: An object containing authentication parameters.
  - `app`: The name of the application to be authenticated (e.g. "shopify"). Required if you do not specify `category`
  - `category`: The name of the Unified API category to show (e.g. "commerce"). Required if you do not specify `app`
  - `callback`: A callback function to be executed after authentication.
  - `useUnifiedSettings`: Boolean indicating whether to use unified settings.
  - `integrationId`: The ID of the integration for authentication.


## Usage Example – Alloy Embedded

```javascript
const alloy = Alloy();

// Set authentication token
alloy.setToken('your-jwt-auth-token');

// [Alloy Embedded Only] – Install an integration
alloy.install({
  integrationId: 'your-integration-id',
  callback: (response) => {
    console.log(response);
  }
});

```


## Usage Example – Alloy Unified API

```javascript
const alloy = Alloy();

// Set authentication token
alloy.setToken('your-jwt-auth-token');

// [Alloy Unified API Only] – Authenticate an application
alloy.authenticate({
  app: 'your-app-name',
  callback: (response) => {
    console.log(response);
  }
});
```

## Reminders

Make sure to replace placeholder values such as `'your-auth-token'` and `'your-integration-id'` with actual values from your Alloy account.