> ## Documentation Index
> Fetch the complete documentation index at: https://product-discovery.developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript library

> A short introduction to the Voyado Elevate API JavaScript library

The JavaScript library, `esales-api`, is built on top of the [Storefront API v3](/elevate/docs/api/storefront/v3/overview) and is designed to make it easy to communicate with Voyado Elevate via a browser or JavaScript runtime (like Node.js, Deno, and more). It provides methods to make HTTP requests available in the API as well as TypeScript models of the response objects.

## Installation

The `@apptus/esales-api` package is available for installation via npm.

<Card title="@apptus/esales-api" href="https://www.npmjs.com/package/@apptus/esales-api" icon="npm" horizontal />

## API instantiation

To work with the `esales-api`, the `clusterId` received during customer onboarding (or in the credentials tab in the Elevate app) is required, as well as the correct IDs for both `market` and `locale`. Additionally, a `touchpoint` with either `'desktop'` or `'mobile'` must be set. Below, the API object is instantiated as a constant, `api`.

```javascript icon="js" expandable theme={null}
import { elevate } from '@apptus/esales-api';

const api = elevate({
  clusterId: 'w1A2B3C45',
  market: 'UK',
  locale: 'en-GB',
  touchpoint: 'desktop',
  session: () => ({
    customerKey: '306c9b32-d361-43e0-a8ad-ec25eceec7ad',
    sessionKey: '767e867f-bece-4836-b230-16fbde4066cb'
  })
});
```

## Key handling

The `esales-api` should be instantiated with a `session` property, which should be a `function` that returns the session and customer key to use. For more information on the key format and about identifying visitors, see [Visitor identification](/elevate/docs/integration/site-integration/session-management#visitor-identification).

<Tabs>
  <Tab title="Synchronous usage">
    ```javascript icon="js" theme={null}
    const api = elevate({
      ...config,
      session: () => {
        const { id, session } = loadUserInfo();
        return { customerKey: id, sessionKey: session };
      }
    });
    ```
  </Tab>

  <Tab title="Usage with Promise">
    ```javascript icon="js" theme={null}
    const api = elevate({
      ...config,
      session: async () => {
        const { id, session } = await loadUserInfo();
        return { customerKey: id, sessionKey: session };
      }
    });
    ```
  </Tab>
</Tabs>

Additionally, the library offers a way to automatically handle session and customer keys in the browser. They will be generated and locally persisted upon request to `localStorage`, and there are methods to update or reset keys, which should be used when visitors sign in or out.

<Tabs>
  <Tab title="Create localStorage session handler">
    ```javascript icon="js" theme={null}
    import { elevate, localStorageBackedSession } from '@apptus/esales-api';

    const api = elevate({
      ...config,
      session: localStorageBackedSession()
    });
    ```
  </Tab>

  <Tab title="Retrieve sessionKey and customerKey">
    ```javascript icon="js" theme={null}
    import { localStorageBackedSession } from '@apptus/esales-api';

    const session = localStorageBackedSession();
    const { customerKey, sessionKey } = session();

    console.log(customerKey, sessionKey);
    // => 'fb91cf58-a5d7-cca9-f30f-50f745ddd46b', '77661ff6-fba3-4ce4-9da4-609323ea22d1'
    ```
  </Tab>

  <Tab title="Update customerKey">
    ```javascript icon="js" theme={null}
    import { localStorageBackedSession } from '@apptus/esales-api';

    const session = localStorageBackedSession();
    session.updateCustomerKey('822c7ed1-30a6-4ea2-9768-540ae06dbfe1');

    console.log(session().customerKey);
    // => '822c7ed1-30a6-4ea2-9768-540ae06dbfe1'
    ```
  </Tab>

  <Tab title="Reset keys">
    ```javascript icon="js" theme={null}
    import { localStorageBackedSession } from '@apptus/esales-api';

    const session = localStorageBackedSession();
    session.reset();

    console.log(...Object.values(session()));
    // => '85f6104e-6763-4b6e-92f9-a3063d2a3cc8', '31276284-3fa3-45f1-a6cb-fe91ec016244'
    ```
  </Tab>
</Tabs>

## Notifications

The JavaScript library includes methods for making notifications of each type. Once the API object has been instantiated, notifications can easily be made, as session and customer keys are automatically applied. Notifications are made via `fetch()` with the `keepalive` flag, so that browsers do not terminate the requests before they complete, such as when sending a click notification when a link is pressed.

All examples below have instantiated the API object as a constant, `api`.

<Tabs>
  <Tab title="Click">
    ```javascript icon="js" theme={null}
    // @param ticket is present on product and variant
    await api.notify.click("L2FkLWluZm9ybWF0aW9uO2FkX2tleTthZDEwcm9kdWN0X2tleTtQMjs")
    ```
  </Tab>

  <Tab title="Add to cart">
    ```javascript icon="js" theme={null}
    // @param ticket is present on product and variant
    await api.notify.addToCart("L2FkLWluZm9ybWF0aW9uO2FkX2tleTthZDEwcm9kdWN0X2tleTtQMjs")
    ```
  </Tab>

  <Tab title="Add favorite">
    ```javascript icon="js" theme={null}
    // @param productKeyOrPayload a `Product.key` or object with variant or product key
    await api.notify.addFavorite("1001-100")
    await api.notify.addFavorite({ variantKey: "vk_234567"})
    ```
  </Tab>

  <Tab title="Remove favorite">
    ```javascript icon="js" theme={null}
    // @param productKeyOrPayload a `Product.key` or object with variant or product key
    await api.notify.removeFavorite("1001-100")
    await api.notify.removeFavorite({ variantKey: 'vk_234567' })
    ```
  </Tab>
</Tabs>

## Queries

Queries can be made by passing query parameters as an object and, for most types of queries, an optional body. The body is used to configure the types of data that will be returned from the API.

All examples below have instantiated the API object as a constant, `api`, and will therefore automatically include query parameters for `market`, `locale`, `touchpoint`, `sessionKey`, and `customerKey`. They show minimal usage: only the required parameters, and no request body. For the full list of parameters and body options, see the [API specification](/elevate/docs/api/storefront/v3/overview).

<Tabs>
  <Tab title="Autocomplete">
    ```javascript icon="js" theme={null}
    const result = await api.query.autocomplete({ q: 'lawnm' });
    // Use the autocomplete result
    ```

    API reference: [Autocomplete query](/elevate/docs/api/storefront/v3/queries/autocomplete)
  </Tab>

  <Tab title="Cart page">
    ```javascript icon="js" theme={null}
    const result = await api.query.cartPage({ cart: '31-8764-0|41-2103-0' });
    // Use the cart page result
    ```

    API reference: [Cart page query](/elevate/docs/api/storefront/v3/queries/cart-page)
  </Tab>

  <Tab title="Content information">
    ```javascript icon="js" theme={null}
    const result = await api.query.contentInformation({ contentKeys: ['storeinfo_2253'] });
    // Use the content information result
    ```

    API reference: [Content information query](/elevate/docs/api/storefront/v3/queries/content-information)
  </Tab>

  <Tab title="Content search page">
    ```javascript icon="js" theme={null}
    const result = await api.query.contentSearchPage({ q: 'stores london' });
    // Use the content search page result
    ```

    API reference: [Content search page query](/elevate/docs/api/storefront/v3/queries/content-search-page)
  </Tab>

  <Tab title="Landing page">
    ```javascript icon="js" theme={null}
    const result = await api.query.landingPage({ pageReference: '/tools/power-tools/drills' });
    // Use the landing page result
    ```

    API reference: [Landing page query](/elevate/docs/api/storefront/v3/queries/landing-page)
  </Tab>

  <Tab title="Navigation tree">
    ```javascript icon="js" theme={null}
    const result = await api.query.navigationTree();
    // Use the navigation tree result
    ```

    API reference: [Navigation tree query](/elevate/docs/api/storefront/v3/queries/navigation-tree)
  </Tab>

  <Tab title="Product page">
    ```javascript icon="js" theme={null}
    const result = await api.query.productPage({ productKey: '31-5053-0' });
    // Use the product page result
    ```

    API reference: [Product page query](/elevate/docs/api/storefront/v3/queries/product-page)
  </Tab>

  <Tab title="Search page">
    ```javascript icon="js" theme={null}
    const result = await api.query.searchPage({ q: 'frying pan' });
    // Use the search result
    ```

    API reference: [Search page query](/elevate/docs/api/storefront/v3/queries/search-page)
  </Tab>
</Tabs>