npm package: @mappingfactory/sdk-js
Description: SDK for Michelin's Navigation and Mapping Services.
Author: Michelin
Latest version: 1.0.5

<h1 align="center">
    @mappingfactory/sdk-js
</h1>

<p align="center">
    Advanced SDK for Michelin's Navigation and Mapping Services.
</p>

## What is `@mappingfactory/sdk-js`

The `@mappingfactory/sdk-js` is a comprehensive software development kit that is intended to replace the current Legacy SDK. Its primary goal is to harness Michelin's navigation and mapping services, delivering advanced features such as route calculation and map display to boost the Mapping Factory division's capabilities.

# Get Started

### Table of Contents

-   [Development environment setup](#development-environment-setup)
-   [Installation](#installation)
-   [Search](#search)
-   [Direction API](#direction-api)

## Development Environment Setup

To run this project locally, navigate to the Project Directory and follow these steps:

### Install Dependencies:

Use `npm` to install the project's dependencies:

```shell
npm install
```

### Build the Project for Development:

Build the project using the following command. This will compile and bundle the JavaScript files and other assets:

```shell
npm run build:dev
```

### Start the Development Server:

To preview the project locally, you can use `npx serve`. This will start a local server, and you can access the project in your browser at the following URL: http://localhost:3000.

```shell
npx serve
```

## Installation

You can install the `@mappingfactory/sdk-js` package using one of the following methods:

### Option 1: Using jsDelivr CDN

Include the following script tag in your HTML file to load the `@mappingfactory/sdk-js` library from the jsDelivr CDN:

```html
<script src="https://cdn.jsdelivr.net/npm/@mappingfactory/sdk-js{version}/dist/michelin-sdk.min.js"></script>
```

> Note: Replace {version} with the desired version of the library.

#### Usage in a script tag

````
const { MichelinSDKClient } = window.MichelinSDK

const sdk = new MichelinSDKClient({
  apiKey: "YOUR_API_KEY"
})

```


### Option 2: Using npm

If you prefer to use `npm` and manage dependencies with a package manager, you can install the `@mappingfactory/sdk-js` package by running the following command:

```shell
npm install @mappingfactory/sdk-js
````

> Note: After installation, you can use the package in your JavaScript project.

#### CommonJS (CJS) Module

If you are using CommonJS (CJS) modules, import the `@mappingfactory/sdk-js` package as follows:

```js
const { MichelinSDKClient } = require('@mappingfactory/sdk-js');
```

#### Warning about Node usage

If you are using a version of Node older than version `18`, `fetch` is not included by default and the SDK might
throw an error. To fix this, you can use a polyfill like `isomorphic-fetch` and import it before using the SDK:

```js
const fetch = require('isomorphic-fetch');
const { MichelinSDKClient } = require('@mappingfactory/sdk-js');
```

#### ECMAScript Module (ESM)

If you are using ECMAScript modules (ESM), import the `@mappingfactory/sdk-js` package as follows:

```js
import { MichelinSDKClient } from '@mappingfactory/sdk-js';
```

> Note: Make sure your project's build setup supports CJS or ESM modules based on your preference.

---

# Michelin SDK

## Search

The `Search` class of the `MichelinSDKClient`, which offers functionality for searching and geocoding locations using the Michelin API, will be discussed in this section. The SDK enables you to carry out location searches using a variety of criteria and retrieve results in an approachable format.

### Setting up the MichelinSDKClient

To use the `MichelinSDKClient`'s Search class, you need to use the `loadSearchLibrary` function that will create an instance of the `Search` class. Here's a basic setup:

```javascript
// Replace 'YOUR_API_KEY' with your actual Michelin API key
const apiKey = 'YOUR_API_KEY';

const sdk = new MichelinSDKClient({ apiKey });

// Load and initialize the Search class
const search = await sdk.loadSearchLibrary();

// You can also access the Search class directly from the MichelinSDKClient instance after initialization using `loadSearchLibrary`
const search = sdk.Search;
```

#### Available Options

| Name   | Type    | Description                              |
| ------ | ------- | ---------------------------------------- |
| apiKey | string  | Your Michelin API key                    |
| locale | string? | <kbd>Optional</kbd><br>Default : `en-US` |

### Geocoding

The Michelin SDK provides a function that allows you to convert a free text address into geographic coordinates (latitude and longitude). To perform a geocoding search, use the geocoding method of the Search class:

```javascript
const address = 'Paris, France';
const options = {
  limit: 5,
  language: 'en-US',
  // Add more options if needed
};

try {
  const result = await search.geocoding({ address, ...options });
  console.log(result);
} catch (error) {
  console.error('Geocoding failed:', error.message);
}
```

> In this example, we perform a geocoding search for the address `"Paris, France"` with additional options such as limiting the results to 5 and specifying the language as English _(en-US)_.

#### Available Options

| Name      | Type            | Description                                                                                                                     | API Query                                                                                                                                                                                                                                                                                                                                     | API Query                                                                      |
| --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| address   | string          | <em>URL-encoded free formed text containing the address to geocode.</em>                                                        | Code example<br>`search.geocoding({ address: "1 rue de la paix" })` column                                                                                                                                                                                                                                                                    | `?address=1%20rue%20de%20la%20paix`                                            |
| filter    | string?         | <kbd>Optional</kbd><br> <em>List of filters applied to restrict the search to certain parameters, separated by semicolons.</em> | Code example<br>`search.geocoding({ address: "1 rue de la paix", filter: "country:BE,NL,LU" })`<br>Note<br>Actually only `country` filter is available, but this feature will be implemented to allow future filters.<br>No check will be done on key/value.                                                                                  | `?address=1%20rue%20de%20la%20paix&filter=country:BE,NL,LU`                    |
| language  | string?         | <kbd>Optional</kbd><br>Default : `en-US`                                                                                        | Code example<br>`search.geocoding({ address: "1 rue de la paix", language: "en-US" })`                                                                                                                                                                                                                                                        | `?address=1%20rue%20de%20la%20paix&language=en-US`                             |
| countries | string[]?       | <kbd>Optional</kbd><br>This parameter is used to prioritize a list of countries on the search.                                  | Code example<br>`search.geocoding({ address: "1 rue de la paix", countries:["BE", "NL", "LU"] })`                                                                                                                                                                                                                                             | `?address=1%20rue%20de%20la%20paix&filter=country:BE,NL,LU`                    |
| limit     | string\|number? | <kbd>Optional</kbd><br>Default : `5`                                                                                            | Code example<br>`search.geocoding({ address: "1 rue de la paix", limit:10 })`                                                                                                                                                                                                                                                                 | `?address=1%20rue%20de%20la%20paix&limit=10`                                   |
| bounds    | object?         | <kbd>Optional</kbd><br>Contains : <br>`sw_corner` - `object`<br>`ne_corner` - `object`                                          | Code example<br>`search.geocoding({ address: "1 rue de la paix", bounds: { sw_corner: { latitude: 37.7749, longitude: -122.4194 }, ne_corner: { latitude: 37.7888, longitude: -122.3991 } } })` <br>Note<br>`proximity` parameter and `bounds` parameter are mutually exclusive. `proximity` parameter takes precedence when both are passed. | `?address=1%20rue%20de%20la%20paix&bounds=37.7749,-122.4194;37.7888,-122.3991` |
| proximity | object?         | <kbd>Optional</kbd><br>Contains : <br>`latitude` - `number`<br>`longitude` - `number`                                           | Code example<br>`search.geocoding({ address: "1 rue de la paix", proximity: { latitude: 37.7749, longitude: -122.4194 } })`<br>Note<br>`proximity` parameter and bounds parameter are mutually exclusive. `proximity` parameter takes precedence when both are passed.                                                                        | `?address=1%20rue%20de%20la%20paix&proximiy=37.7749,-122.4194`                 |

### Autocomplete Widget

The MichelinSDKClient provides an autocomplete widget that allows users to search for locations and select them from a dropdown list. To generate the autocomplete widget, use the autocomplete method of the Search class:

```javascript
const element = document.getElementById('autocomplete');
const options = {
  debounce: 300,
  allowTab: true,
  input: {
    placeholder: 'Search for a location',
  },
  dropdown: {
    noResultsOpen: true,
    position: 'right',
  },
  dropdownItem: {
    highlight: true,
  },
  // Add more options if needed
};

try {
  const autocomplete = await search.autocomplete(element, options);

  autocomplete._on('selected', (result) => {
    console.log('Selected location:', result);
  });
} catch (error) {
  console.error('Autocomplete initialization failed:', error.message);
}
```

> In this example, we generate an autocomplete widget for the HTML element with the ID `"autocomplete"` and provide additional options like debounce time, placeholder text, and auto-fill behavior.

> The `_on('selected')` method allows you to listen for the event when the user selects a location from the autocomplete dropdown. When a location is selected, the associated callback function will be executed, and the selected location information will be logged to the console.

### Events supported

| Event Name | Description                                                   | Parameters (callbacks)            |
| ---------- | ------------------------------------------------------------- | --------------------------------- |
| opened     | Triggered when the list of suggestions is displayed.          | None.                             |
| closed     | Triggered when the list of suggestions is closed.             | None.                             |
| clear      | Triggered when when the search input is emptied by the user   | None.                             |
| search     | Triggered when a query is sent for results.                   | data (Object): The query object   |
| noResults  | Triggered if no suggestion is proposed after the input entry. | None.                             |
| selected   | Triggered when a suggestion is selected by the user.          | data (Object): The result object  |
| success    | Triggered when the results have been fetched.                 | data (Object[]): An array of data |
| error      | Triggered when an error occurs when making the request.       | error (Error): The error object   |

This chapter covered the basic usage of the `MichelinSDKClient`'s Search class and its functionalities, including geocoding and the autocomplete widget. By integrating the `MichelinSDKClient` into your applications, you can provide enhanced location search capabilities and enrich your user experience.

### Available Options

| Name                                    | Type       | Description                                                                                                                                                                                                             | API Call                                                                                                                                                  | Configuration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| input                                   | `Object`   | This parameter allows you to specify options for the input field.                                                                                                                                                       |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| input.id (optional)                     | `string`   | Id to use for the input (default: `msdk-input`)                                                                                                                                                                         |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| input.name (optional)                   | `string`   | Name to use for the input (default: `msdk-input-name`)                                                                                                                                                                  |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| input.class (optional)                  | `string`   | Class to use for the input (default: `michelin-search__autocomplete-input`)                                                                                                                                             |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| input.classNames (optional)             | `string`   | Additional class names to use for the input (default: ``)                                                                                                                                                               |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| input.placeholder (optional)            | `string`   | Placeholder to use for the input (default: ``)                                                                                                                                                                          |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| input.autoComplete (optional)           | `boolean`  | Whether or not to automatically fill the input with the selected result (default: `false`)                                                                                                                              |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Search Parameters                       | `Object`   |                                                                                                                                                                                                                         |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| countries                               | `string[]` | It is used to specify a list of countries for the search field. Its values have to be a list of codes based upon the ISO 3166-1 alpha-2 format like. Validation: Ensure that the country code is correct.               | `filter=country:BE,NL,LU`                                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| include_poi                             | `boolean`  | If this parameter is true, API will search for both addresses and POI. The results may or may not contain the POIs basing on the query. If the value is false, it will only search for addresses. Default value: `true` | `include_poi=true`                                                                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| language                                | `string`   | The language to be used for result. Example: `language=en-GB`. Validation: Ensure that the language code is correct.                                                                                                    | `LANGUAGE={parameters.language}`                                                                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| limit                                   | `number`   | The maximum number of result items to be included in the response. Default value: `5`                                                                                                                                   | `limit=2`                                                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| bounds                                  | `object?`  | Optional Contains: `sw_corner` - `object` `ne_corner` - `object`                                                                                                                                                        |                                                                                                                                                           | Allow to restrict the results within the given geographic bounding box represented by southwest and northeast corners. It is an object with two properties: `sw_corner` (South West Corner) and `ne_corner` (North East Corner). Note: proximity parameter and bounds parameter are mutually exclusive. proximity parameter takes precedence when both are passed. Based on the code example in the description column `?address=1%20rue%20de%20la%20paix&bounds=37.7749,-122.4194; 37.7888,-122.3991` |
| proximity                               | `object?`  | Optional Contains: `latitude` - `number` `longitude` - `number`                                                                                                                                                         |                                                                                                                                                           | Allow to favour the closest results to the given geographical coordinates. The use of this parameter is recommended as it provides more accurate results. Note: proximity parameter and bounds parameter are mutually exclusive. proximity parameter takes precedence when both are passed. Based on the code example in the description column `?address=1%20rue%20de%20la%20paix&proximiy=37.7749,-122.4194`                                                                                         |
| autofill                                | `boolean`  | Enable or disable browser autofill functionality. Default: `False`                                                                                                                                                      |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| debounce                                | `number`   | Responsible for setting delay time duration that counts after typing is done for the request to start. This attribute will set the fire rate limit (in milliseconds) on the keyup event callback. Default: `300`        |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| threshold                               | `number`   | Responsible for setting the threshold value of the minimum character length where the request can start. Default: `3`                                                                                                   |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdown                                |            | Responsible for the results list element rendering, interception, and customizing                                                                                                                                       |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdown.tag (optional)                 | `string`   | Default: `ul`                                                                                                                                                                                                           | `dropdown: { tag: 'ul', id: 'msdk-dropdown', class: 'michelin-search__autocomplete-dropdown', classNames: '', noResultsOpen: true, position: 'bottom', }` |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdown.id (optional)                  | `string`   | Default: `msdk-dropdown`                                                                                                                                                                                                |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdown.class (optional)               | `string`   | Default: `michelin-search__autocomplete-dropdown`                                                                                                                                                                       |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdown.position (optional)            | `string`   | Default: `bottom`                                                                                                                                                                                                       |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdown.classNames (optional)          | `string`   | A list of class names that will be added on top of the .class                                                                                                                                                           |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdown.allowTab (optional)            | `boolean`  | Default: `true`                                                                                                                                                                                                         |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdown.noResultsOpen (optional)       | `boolean`  | Default: `false`                                                                                                                                                                                                        |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdownItem (optional)                 |            | Responsible for the result item element rendering, interception, and customizing                                                                                                                                        |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdownItem.tag (optional)             | `string`   | Default: `li`                                                                                                                                                                                                           | `dropdownItem: { tag: 'li', id: 'msdk-dropdown-item', class: 'michelin-search__autocomplete-dropdown-item', classNames: '', highlight: true, }`           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdownItem.id (optional)              | `string`   | Default: `msdk-dropdown-item`                                                                                                                                                                                           |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdownItem.classNames (optional)      | `string`   | A list of class names that will be added on top of the .class                                                                                                                                                           |                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dropdownItem.class (optional)           | `string`   | Default: `michelin-search__autocomplete-dropdown-item`                                                                                                                                                                  |                                                                                                                                                           |
| dropdownItem.highlight (optional)       | `boolean`  | Default: `true`                                                                                                                                                                                                         |
| dropdownItem.highlightTag (optional)    | `string`   | Default: `mark`                                                                                                                                                                                                         |
| dropdownItem.highlightClass (optional)  | `string`   | Default: `michelin-search__autocomplete-dropdown-item--highlight`                                                                                                                                                       |
| dropdownItem.truncateDetails (optional) | `boolean`  | Default: `true`                                                                                                                                                                                                         |

## Direction API

The Michelin Directions API allows developers to access routing and directions information for different modes of transportation, such as driving, walking, or cycling. The `DirectionWrapper` class provides a simplified way to interact with this API by handling API key authentication and setting various route options.

### Setting up the DirectionWrapper

To use the MichelinSDKClient's `DirectionWrapper` class, you need to use the `loadDirectionLibrary` function that will create an instance of the `DirectionWrapper` class and returns the `Mapping Directions API Client` to make requests. Here's a basic setup:

```javascript
...
// Replace 'YOUR_API_KEY' with your actual Michelin API key
const apiKey = 'YOUR_API_KEY';

const sdk = new MichelinSDKClient({ apiKey });

// Load and initialize the `DirectionWrapper` class and resolve the promise with the Direction wrapper
const directionWrapper = await sdk.loadDirectionLibrary();

// You can access the `DirectionWrapper` class directly from the MichelinSDKClient instance
const direction = sdk.Direction;
```

### Setting Direction Options

The `DirectionWrapper` provides methods to set various options that affect the route calculation and direction retrieval process. These options include transportation mode, waypoints, geometries, duration, language, and more :

```javascript
// Set options for route calculation using the `DirectionWrapper` class
const formData = {
  coordinates: [
    { latitude: 48.8566, longitude: 2.3522 }, // Paris, France
    { latitude: 51.5074, longitude: -0.1278 }, // London, UK
  ],
  mode: 'fastest',
  language: 'en',
};

sdk.Direction.setFormData(formData);
```

### Using a map with the DirectionWrapper

The `DirectionWrapper` class can be used with a map to visualize the route and direction information. Here's an example of how to use the `setMap`, `setTraceWidth`, `setTraceColor`, `showTrace`, and `getTraceVisibility` methods to display the route on a map:

```javascript
// Load and initialize the `DirectionWrapper` class and resolve the promise with the Direction wrapper
const directionWrapper = await sdk.loadDirectionLibrary();

// Load and initialize the `MapLibreWrapper` class and resolve the promise with the MapLibre Client
const maplibregl = await sdk.loadMapLibreLibrary();

// Set up the map
const map = new maplibregl.Map({
  container: 'map',
  style: 'my-map-style.json',
  center: [2.3522, 48.8566],
  zoom: 5,
});

// Set the map for the `DirectionWrapper` class
sdk.Direction.setMap(map);

map.on('load', async () => {
  // Get the direction information (We assume in this example that the `formData` has already been set)
  const dataSource = await directionWrapper.client.search();

  // Show the trace on the map for the default layer
  const route = dataSource.routes[0];
  sdk.Direction.showTrace({
    visible: true,
    route,
  });

  // Set the trace width and color for the default layer
  sdk.Direction.setTraceWidth({
    width: 5,
  });
  sdk.Direction.setTraceColor({
    color: '#ff0000',
  });

  // Get the visibility of the trace for the default layer
  const traceVisible = sdk.Direction.getTraceVisibility();

  if (traceVisible) {
    console.log('Trace is visible!');

    sdk.Direction.removeTrace(); // This will remove the default trace from the map
    console.log('Trace has been removed from the map!');
  }
});
```

Now here is an example if you have multiple routes and want to display them on the map:

```javascript
// Load and initialize the `DirectionWrapper` class and resolve the promise with the Direction wrapper
const directionWrapper = await sdk.loadDirectionLibrary();

// Load and initialize the `MapLibreWrapper` class and resolve the promise with the MapLibre Client
const maplibregl = await sdk.loadMapLibreLibrary();

// Set up the map
const map = new maplibregl.Map({
  container: 'map',
  style: 'my-map-style.json',
  center: [2.3522, 48.8566],
  zoom: 5,
});

// Set the map for the `DirectionWrapper` class
sdk.Direction.setMap(map);

map.on('load', async () => {
  // Get the direction information (We assume in this example that the `formData` has already been set)
  const dataSource = await directionWrapper.client.search();

  const firstRoute = dataSource.routes[0];
  const lastRoute = dataSource.routes[dataSource.routes.length - 1];

  // Show the trace on the map for a specific layer, if the layer do not exists it will be created
  sdk.Direction.showTrace({
    visible: true,
    route,
    layerId: 'first-route',
  });

  // Set the trace width and color for a specific layer
  sdk.Direction.setTraceWidth({
    width: 5,
    layerId: 'first-route',
  });

  sdk.Direction.setTraceColor({
    color: '#ff0000',
    layerId: 'first-route',
  });

  // Here we show the trace on the map for `last-route` layer, with defaults values for color and width
  sdk.Direction.showTrace({
    visible: true,
    route,
    layerId: 'last-route',
  });

  // Get the visibility of the trace for the default layer
  const firstRouteVisible = sdk.Direction.getTraceVisibility('first-route');
  const lastRouteVisible = sdk.Direction.getTraceVisibility('last-route');

  if (firstRouteVisible && lastRouteVisible) {
    console.log('All routes traces are visible!');

    // Remove the last-route trace from the map
    sdk.Direction.removeTrace('last-route');
  }

  // Now let's toggle the visibility of the first route trace based on a button we have in the DOM

  const button = document.getElementById('btn');

  button.addEventListener('click', () => {
    // We first get the current visibility of the trace
    const isVisible = sdk.Direction.getTraceVisibility('first-route');

    // And then we toggle the visibility of the trace, if you do not pass a `route` parameter, the DirectionWrapper will use the last route used
    sdk.Direction.showTrace({
      visible: !isVisible,
      layerId: 'first-route',
    });
  });
});
```

-   The `setMap` method saves a reference of the map and creates a new maplibre layer for the route and start point.
-   The `setTraceWidth` and `setTraceColor` methods allows you to set the width and color of the route and start point.
-   You can remove a trace from the map using the `removeTrace` method.
-   Finally, the `showTrace` method toggles the visibility of the route on the map and updates the data source of the map with the direction information. You can also check if the trace is visible on the map using the `getTraceVisibility` method.

### Available Options

| Name                                    | Type      | Description                                                                    | Mandatory | Allowed Values                                             |
| --------------------------------------- | --------- | ------------------------------------------------------------------------------ | --------- | ---------------------------------------------------------- |
| currency                                | `string`  | The currency for cost-related information.                                     | Optional  | Any valid currency code (e.g., "USD", "EUR", "GBP")        |
| unit                                    | `string`  | The unit of measurement.                                                       | Optional  | "m" (meters), "km" (kilometers), "mi" (miles), "ft" (feet) |
| vehicleType                             | `string`  | The type of vehicle.                                                           | Optional  | Any valid vehicle type                                     |
| annotations                             | `string`  | Allows to specify which metadata to have in the result. Only for "truck" mode. | Optional  | Any valid value in ('maxspeed', 'congestion', 'duration')  |
| vehicleCommercial                       | `string`  | The commercial name of the vehicle.                                            | Optional  | Any valid commercial name                                  |
| url                                     | `string`  | The URL for the API request.                                                   | Optional  | Any valid URL                                              |
| http_request_method                     | `string`  | The HTTP request method.                                                       | Optional  | "GET", "POST", "PUT", "DELETE"                             |
| alternatives                            | `boolean` | Indicates if alternative routes should be included.                            | Optional  | true, false                                                |
| avoid                                   | `string`  | Specifies features to avoid along the route.                                   | Optional  | Any feature to avoid                                       |
| car_type                                | `string`  | The type of car for the route.                                                 | Optional  | Any valid car type                                         |
| coordinates                             | `array`   | The coordinates for the waypoints.                                             | Mandatory | Array of valid coordinates                                 |
| electricity_consumptions_per_hundred_km | `string`  | Electricity consumption per 100 km.                                            | Optional  | Any valid electricity consumption value                    |
| electricity_cost                        | `number`  | The cost of electricity per unit.                                              | Optional  | Any valid cost value                                       |
| fuel_consumptions_per_hundred_km        | `string`  | Fuel consumption per 100 km.                                                   | Optional  | Any valid fuel consumption value                           |
| fuel_cost                               | `number`  | The cost of fuel per unit.                                                     | Optional  | Any valid cost value                                       |
| fuel_type                               | `string`  | The type of fuel for the vehicle.                                              | Optional  | Any valid fuel type                                        |
| geometries                              | `string`  | The type of geometries for the route.                                          | Optional  | "polyline", "geojson", "encodedpolyline"                   |
| language                                | `string`  | The language for route instructions.                                           | Optional  | Any valid language code (e.g., "en", "fr", "es")           |
| mentions                                | `string`  | Additional mentions for the route.                                             | Optional  | Any additional mention                                     |
| mode                                    | `string`  | The mode of transportation.                                                    | Optional  | Any valid mode of transportation                           |
| motorization                            | `string`  | The motorization of the vehicle.                                               | Optional  | Any valid motorization type                                |
| overview                                | `string`  | The type of overview for the route.                                            | Optional  | "simplified", "full", "false"                              |
| pois_corridor_options                   | `string`  | POI corridor options for the route.                                            | Optional  | Any valid POI corridor option                              |
| steps                                   | `boolean` | Indicates if steps should be included in the route.                            | Optional  | true, false                                                |
| traffic                                 | `string`  | The type of traffic data to consider.                                          | Optional  | Any valid traffic type                                     |
| type                                    | `string`  | The type of the route.                                                         | Optional  | Any valid route type                                       |
| vehicle_adr_tunnel_restriction_code     | `string`  | ADR tunnel restriction code.                                                   | Optional  | Any valid ADR tunnel restriction code                      |
| vehicle_axle_weight                     | `string`  | The axle weight of the vehicle.                                                | Optional  | Any valid axle weight value                                |
| vehicle_commercial                      | `string`  | The commercial type of the vehicle.                                            | Optional  | Any valid commercial type                                  |
| vehicle_height                          | `string`  | The height of the vehicle.                                                     | Optional  | Any valid height value                                     |
| vehicle_length                          | `string`  | The length of the vehicle.                                                     | Optional  | Any valid length value                                     |
| vehicle_load_type                       | `string`  | The load type of the vehicle.                                                  | Optional  | Any valid load type                                        |
| vehicle_max_speed                       | `string`  | The maximum speed of the vehicle.                                              | Optional  | Any valid maximum speed value                              |
| vehicle_type                            | `string`  | The type of the vehicle.                                                       | Optional  | Any valid vehicle type                                     |
| vehicle_weight                          | `string`  | The weight of the vehicle.                                                     | Optional  | Any valid weight value                                     |
| vehicle_width                           | `string`  | The width of the vehicle.                                                      | Optional  | Any valid width value                                      |
| waypoints                               | `array`   | The waypoints for the route.                                                   | Optional  | Array of valid waypoints                                   |

### Retrieving Directions

Once the options are set, you can request directions and route information using the Michelin Directions API:

```javascript
try {
  // Replace 'YOUR_API_KEY' with your actual Michelin API key
  const apiKey = 'YOUR_API_KEY';

  const sdk = new MichelinSDKClient({ apiKey });

  // Load and initialize the `DirectionWrapper` class and resolve the promise with the Direction wrapper
  const directionWrapper = await sdk.loadDirectionLibrary();

  // Set options for route calculation using the `DirectionWrapper` class
  const formData = {
    coordinates: [
      { latitude: 48.8566, longitude: 2.3522 }, // Paris, France
      { latitude: 51.5074, longitude: -0.1278 }, // London, UK
    ],
    mode: 'fastest',
    language: 'en',
  };
  sdk.Direction.setFormData(formData);

  const directions = await directionWrapper.client.search(); // This will uses the `formData` set above by the `DirectionWrapper` function `setFormData`
  console.log('Directions:', directions);
} catch (error) {
  console.error('Failed to retrieve directions:', error.message);
}
```

## Roadsheet API

The Michelin Roadsheet API enables developers to generate detailed navigation instructions for a given route, complementing the Directions API. The `RoadSheetWrapper` class ensures a hassle-free interaction with this API, managing form data and offering customizable navigation icons.

### Setting up the RoadSheetWrapper

To leverage the `RoadSheetWrapper` via the `MichelinSDKClient`, you should call the `loadRoadsheetLibrary` function. This function instantiates the `RoadSheetWrapper` class and returns the `Roadsheet Client` that facilitates request-making:

```javascript
...
// Replace 'YOUR_API_KEY' with your genuine Michelin API key
const apiKey = 'YOUR_API_KEY';

const sdk = new MichelinSDKClient({ apiKey });

// Load and initialize the `RoadSheetWrapper` class and return the Roadsheet Client upon resolving the promise
const roadsheetWrapper = await sdk.loadRoadsheetLibrary();
/**
 * The RoadsheetWrapper is also accessible directly from the MichelinSDKClient instance : `sdk.Roadsheet`
 */

const routePoints = {routes: [{...}], waypoints: [{...}, {...}, {...}]};

const html = await roadsheetWrapper.client.getHtml(routePoints.routes[0], routePoints.waypoints, routePoints.language);

```

### Configuring Roadsheet Options

The `RoadSheetWrapper` class provides methods to specify various options for your roadsheet generation, allowing developers to customize icons, units, language, date, and other elements:

```javascript
// Define options for your roadsheet using the `RoadSheetWrapper` class
const formData = {
  language: 'en-GB',
  startDate: Date.now(),
  disabledManeuvers: ['merge', 'continue'],
  primaryMentions: ['road_sign', 'toll_collection'],
  maxSecondaryMentions: 0,
};

sdk.Roadsheet.setFormData(formData);
```

By setting these options, developers can generate a roadsheet tailored to the specific needs and preferences of their application's users.

> The `RoadSheetWrapper` exposes the `@mappingfactory/roadsheet` members :
> `client`: The Roadsheet Client
> `icons`: The Roadsheet Icons
> `utils`: The Roadsheet Utils static class
> You can access them directly from the MichelinSDKClient instance : `sdk.Roadsheet.client`, `sdk.Roadsheet.icons`, `sdk.Roadsheet.utils`

## MapLibre API

The Michelin MapLibre API offers developers the ability to integrate powerful map visualization capabilities into their applications. Using the `MapLibreWrapper` class, one can seamlessly embed maps by leveraging the MapLibre GL library without the overhead of manual integrations.

### Setting up the MapLibreWrapper

To employ the `MapLibreWrapper` through the `MichelinSDKClient`, you'll want to invoke the `loadMapLibreLibrary` function. This function spawns an instance of the `MapLibreWrapper` class and bestows you with the `MapLibre Client` designed for rendering and controlling map views:

```javascript
// Replace 'YOUR_API_KEY' with your actual Michelin API key
const apiKey = 'YOUR_API_KEY';

const sdk = new MichelinSDKClient({ apiKey });

// Kickstart the `MapLibreWrapper` class and retrieve the MapLibre Client once the promise is resolved
const mapLibreClient = await sdk.loadMapLibreLibrary();

// You can now directly interface with the `MapLibreWrapper` through the MichelinSDKClient instance
const maplibre = sdk.MapLibre;
```

> **Note**: This integration utilizes MapLibre, an open-source mapping library. If you're familiar with MapLibre, you can use it as usual within this context. For comprehensive details or if you're new to MapLibre, consult their official documentation [here](https://maplibre.org/maplibre-gl-js/docs/).

---

## License

Licensed under the [MIT](./LICENSE) License.