npm package: @commercelayer/algolia-importer
Description: > A Javascript library that lets you easily import your ecommerce catalog into Algolia.
Author: Alessandro Casazza
Latest version: 1.0.10

# Commerce Layer Algolia Importer

> A Javascript library that lets you easily import your ecommerce catalog into Algolia.

### What is Commerce Layer?

[Commerce Layer](https://commercelayer.io/) is a headless platform that lets you easily build enterprise-grade ecommerce into any website, by using the language, CMS, and tools you already master and love.

### Table of contents

- [How it works](#how-it-works)
- [Getting started](#getting-started)
  - [Installation](#installation)
  - [Import](#import)
- [Usage](#usage)
  - [The importer function](#the-importer-function)
  - [The items array](#the-items-array)
  - [Default settings](#default-settings)
- [Adding prices to the search](#adding-prices-to-the-search)

## How it works

Commerce Layer Algolia Importer is designed to make it quick and simple to import your products data, index them into [Algolia](https://www.algolia.com/), and eventually get their prices from Commerce Layer and add them to the search.

> This importer is CMS-agnostic — you can import your content data from any CMS of your choice, according to any content model you defined.

## Getting started

To get started and import your data into Algolia you need to install the importer and retrieve your credentials from your Algolia account.

### Installation

Commerce Layer Algolia Importer is available as an [npm package](https://www.npmjs.com/package/@commercelayer/algolia-importer):

```
// npm
npm install @commercelayer/algolia-importer

// yarn
yarn add @commercelayer/algolia-importer
```

### Import

You can use the ES6 default import as follows:

```
import importer from '@commercelayer/algolia-importer'
```

## Usage

### The importer function

Commerce Layer Algolia `importer` function returns as a promise an array of Algolia `index` objects — one for each of your selling countries (associated with the specified translation). You need to pass to it as a parameter an object containing at least:

- `algoliaConfig` — your Algolia app ID and admin API key
- `items` — the list of products you want to index

```
importer({
  algoliaConfig: {
    appId: 'your-algolia-app-id',
    adminApiKey: 'your-algolia-admin-api-key'
  },
  items: yourItems,
}).then((results) => {
    console.log(results)
})
```

### The items array

`items` is an array of objects. It has to be properly built by specifying the language code, the country code, and a list of key/value parameters related to the single variants:

```
// Typescript types

{
  [languageCode: string]: {
    [countryCode: string]: {
        customRanking: number
        reference: string
        objectID: string
        category: string[] | string
        description: string
        name: string
        code: string
        image: string
    }[],
    marketId?: string
  }[]
}[]

// Example

[
  {
    'en-US': [
      {
        us: [
          {
            customRanking: 0,
            reference: 'your-reference',
            objectID: 'your-objectID',
            category: 'your-category',
            description: 'your-description',
            name: 'your-variant-name',
            code: 'your-sku-code',
            image: 'your-image-url'
          }
        ]
      }
    ]
  }
]
```

> For each item you can define a custom ranking by setting the `customRanking` parameter — the lower its value the higher the item will be ranked within the search results.

### Default settings

Commerce Layer Algolia importer comes with some default values for its main parameters:

```
showPrice: false,
clConfig: {
  clientId: '',
  endpoint: '',
},
algoliaIndexPrefix: 'store'
algoliaSettings: {
  searchableAttributes: [
    'category',
    'code',
    'description',
    'name',
    'reference',
  ],
  customRanking: ['asc(customRanking)'],
  attributesForFaceting: ['category'],
  distinct: 1,
  attributeForDistinct: 'reference',
  replicas: [],
}
```

> The `algoliaSettings` object can be overridden at your leisure — please refer to [Algolia documentation](https://www.algolia.com/doc/api-reference/settings-api-parameters/) for more info on how to set their API parameters.

## Adding prices to the search

Our Algolia importer lets you import from Commerce Layer the prices of each product you want to index and sort (ascending or descending) your search result by price. To do that, just set the `showPrice` parameter to `true` and add the `clConfig` object with your Commerce Layer organization credentials, remembering to specify the market in scope at a country code level in the `items` array:

```
const items = [
  {
    'en-US': [
      {
        us: [
          {
            customRanking: 0,
            reference: 'your-reference',
            objectID: 'your-objectID',
            category: 'your-category',
            description: 'your-description',
            name: 'your-variant-name',
            code: 'your-sku-code',
            image: 'your-image-url'
           }
        ],
        marketId: 'your-market-id'
      }
    ]
  }
]

importer({
  algoliaConfig: {
    appId: 'your-algolia-app-id',
    adminApiKey: 'your-algolia-admin-api-key'
  },
  items: items,
  showPrice: true,
  clConfig: {
    clientId: 'your-client-id',
    endpoint: 'https://yourdomain.commercelayer.io'
  }
})
```

> This way, all the prices are added to the related index and two [Algolia replicas](https://www.algolia.com/doc/api-reference/api-parameters/replicas/) (`price_asc` and `price_desc`) are automatically created.

---

### License

This repository is published under the [MIT](LICENSE) license.