npm package: @shelf/ssp-sdk
Description: Self Service Portal SDK
Author: Rostyslav Horytskyi
Latest version: 12.0.1

# @shelf/ssp-sdk [![CircleCI](https://circleci.com/gh/shelfio/agent-assist-sdk/tree/master.svg?style=svg)](https://circleci.com/gh/shelfio/agent-assist-sdk/tree/master)![](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)

## ShelfSSPSDK

The `ShelfSSPSDK` is a JavaScript library that allows you to easily integrate and interact with the `ShelfSSP` iframe-based Single-Page Application.
It provides methods for initializing the `ShelfSSP` iframe, constructing URLs, tracking URL changes, handling events, and sending messages to the `ShelfSSP`.

### Install

```
npm install @shelf/ssp-sdk
```

or

```
yarn add @shelf/ssp-sdk
```

#### As script

```
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@shelf/ssp-sdk@:tag-version:/lib/integration.self-service-portal.min.js"></script>
```

### Usage

To use the `ShelfSSPSDK`, import it into your JavaScript or TypeScript file:

```ecmascript 6
import { ShelfSSPSDK } from '@shelf/ssp-sdk';
```
#### Initialize the ShelfSSP iframe

To initialize the `ShelfSSP` iframe, use the initialize method:

```ecmascript 6
ShelfSSPSDK.initialize({
  element: document.getElementById('shelf-ssp-container'),
  sspURL: 'https://example.com/ssp',
  lang: 'en',
  slug: 'product',
  searchParams: { category: 'electronics', brand: 'apple' },
  onReady: () => {
    console.log('ShelfSSP is ready');
  }
});
```

The initialize method takes an object with the following properties:
  - `element (HTMLElement)`: The DOM element where the `ShelfSSP` iframe will be appended.
  - `sspURL (string)`: The base URL of the `ShelfSSP`.
  - `lang (string)`: The language parameter for the `ShelfSSP` URL.
  - `slug (string)`: The slug parameter for the `ShelfSSP` URL.
  - `searchParams (Record<string, string>)`: Additional query parameters for the `ShelfSSP` URL.
  - `onReady (optional function)`: A callback function that will be called when the `ShelfSSP` iframe is loaded and ready.

#### Handle events from the ShelfSSP

To handle events sent from the `ShelfSSP`, use the `on` method:
```ecmascript 6
ShelfSSPSDK.on('event', (data) => {
  console.log('Received event:', data);
});
```
The `on` method takes an event name and a callback function.
The callback function will be called whenever an event with the specified name is received from the `ShelfSSP`.

#### Send messages to the ShelfSSP

To send messages to the ShelfSSP, use the `postMessage` method:
```ecmascript 6
ShelfSSPSDK.postMessage('action', { payload: 'data' })
  .then((response) => {
    console.log('Received response:', response);
  });
```
The `postMessage` method takes a message type and an optional payload.
It returns a promise that resolves with the response from the `ShelfSSP`.

#### Close the ShelfSSP iframe

To close the `ShelfSSP` iframe, use the `close` method:
```ecmascript 6
ShelfSSPSDK.close();
```
The `close` method removes the `ShelfSSP` iframe from the DOM.

## CommunicationChannel

The `CommunicationChannel` class is a utility class that provides methods for initializing and interacting with a communication channel using the `structured-channel` library.

### Usage

To use the `CommunicationChannel` class, import it into your JavaScript or TypeScript file:
```ecmascript 6
import { CommunicationChannel } from '@shelf/sdk-ssp';
```

#### Initialize the Communication Channel

Before using the communication channel, you need to initialize it by calling the `init` method:
```ecmascript 6
await CommunicationChannel.init();
```
The `init` method establishes a connection with the `structured-channel` and prepares the communication channel for sending and receiving messages.

#### Send Messages

To send messages through the communication channel, use the `send` method:
```ecmascript 6
await CommunicationChannel.send('action', { payload: 'data' });
```
The `send` method takes a message type and an optional payload.
It sends the message through the communication channel and returns a promise that resolves with the response from the other end of the channel.

#### Handle Events

To handle events received through the communication channel, use the `on` method:
```ecmascript 6
CommunicationChannel.on('event', (data) => {
  // Handle the event data
});
```
The `on` method takes an event name and a callback function.
The callback function will be called whenever an event with the specified name is received through the communication channel.

#### Stop Handling Events

To stop handling events for a specific event name, use the `off` method:
```ecmascript 6
CommunicationChannel.off('event', callback);
```
The `off` method removes the specified callback function from the event listeners for the given event name.


MIT © [Shelf](https://shelf.io)