npm package: @mimik/public-helper
Description: Public IP helper for mimik microservices
Author: mimik technology inc
Latest version: 3.0.6

<a name="module_public-helper"></a>

## public-helper
The following environment variables are required for custom locations:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| SERVER_LOCATION_LON | longitude of the IP address
| SERVER_LOCATION_LAT | latitude of the IP address
| SERVER_PUBLIC_IPV4 | public IP address

**Example**  
```js
import publicHelper from '@mimik/public-helper';
```
**Example**  
```js
import { PROPERTIES, getLocation, getPublic, setSettings } from '@mimik/public-helper';
```

* [public-helper](#module_public-helper)
    * [module.exports](#exp_module_public-helper--module.exports) ⏏
        * _static_
            * [.PROPERTIES](#module_public-helper--module.exports.PROPERTIES)
        * _inner_
            * _async_
                * [~getLocation(locationProvider, ip, correlationId, options)](#module_public-helper--module.exports..getLocation) ⇒ <code>Promise</code>
                * [~getPublic(locationProvider, cloudProvider, correlationId, options)](#module_public-helper--module.exports..getPublic) ⇒ <code>Promise</code>
            * _sync_
                * [~setSettings(settings, newConfig)](#module_public-helper--module.exports..setSettings) ⇒ <code>object</code>

<a name="exp_module_public-helper--module.exports"></a>

### module.exports ⏏
To note

The following environment variables are required for custom locations:
SERVER_PUBLIC_IPV4 with 52.84.158.59,
SERVER_LOCATION_LON with -122.676,
SERVER_LOCATION_LAT with 45.5235,
LOCATION_PROVIDER with "environment".

**Kind**: Exported member  
<a name="module_public-helper--module.exports.PROPERTIES"></a>

#### module.exports.PROPERTIES
Property associated with the location.

The following environment variables are set by the AWS metadata lookup:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| query[URL_ENV] | local properties filled from AWS metadata | | SERVER_LOCAL_IPV4, INSTANCE_ID, LOCAL_HOSTNAME
| publicQuery[URL_ENV] | public IP address filled from AWS metadata | | SERVER_PUBLIC_IPV4

The following environment variables are used:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| AWS_LOCAL_PROPERTIES | IP address to access instance properties on AWS | 169.254.169.254

**Kind**: static constant of [<code>module.exports</code>](#exp_module_public-helper--module.exports)  
<a name="module_public-helper--module.exports..getLocation"></a>

#### module.exports~getLocation(locationProvider, ip, correlationId, options) ⇒ <code>Promise</code>
The location object has the following structure:
``` javascript
 {
   "type": "Point",
   "coordinates": [ lon, lat],
   .....
 }
```
The result object has the following structure:
``` javascript
 {
   "status": (describing where the data come from),
   "ip": (the public IP address of the server),
   "location": (the location object)
 }
```

When `ip` is not present, SERVER_LOCATION_LON, SERVER_LOCATION_LAT, SERVER_PUBLIC_IPV4 environment variables will be updated.

**Kind**: inner method of [<code>module.exports</code>](#exp_module_public-helper--module.exports)  
**Category**: async  
**Fulfil**: <code>object</code> The location object encapsulated in the result.  

| Param | Type | Description |
| --- | --- | --- |
| locationProvider | <code>object</code> | location provider information to use for getting the location { url, key } (key is optional). |
| ip | <code>string</code> | *Optional* IP address to locate. |
| correlationId | <code>string</code> | Correlation Id to add to the request. |
| options | <code>object</code> | Options associated with the call. Use to pass `metrics` to `rpRetry`. |

<a name="module_public-helper--module.exports..getPublic"></a>

#### module.exports~getPublic(locationProvider, cloudProvider, correlationId, options) ⇒ <code>Promise</code>
The location data has the following structure:
``` javascript
 {
   "status": (describing where the data come from),
   "ip": (the public IP address of the server),
   "localIp": (`in case of AWS` local address),
   "instanceId": (`in case of AWS` id of the instance running the service),
   "location": (the location object)
 }
```
When provided, the locationProvider information has the following structure:
``` javascript
 {
   "url": (URL of the provider),
   "key": (security key associated with the request)
 }
```

on top of SERVER_PUBLIC_IPV4, SERVER_LOCATION_LON and SERVER_LOCATION_LAT the following environment variables will be used:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| SERVER_LOCAL_IPV4 | AWS local IP address
| INSTANCE_ID | id of the instance
| SERVER_ID | id of the server

and in order to set these properties `process.env.AWS_LOCAL_PROPERTIES` is used and defaults to `169.254.169.254`.

**Kind**: inner method of [<code>module.exports</code>](#exp_module_public-helper--module.exports)  
**Category**: async  
**Fulfil**: <code>object</code> The location data.  

| Param | Type | Description |
| --- | --- | --- |
| locationProvider | <code>string</code> \| <code>object</code> | The location provider or `noPublic` when no locationProvider is used or `environment` when the environment variables have the information. |
| cloudProvider | <code>string</code> | Cloud Provider used to run the service (currently limited to `AWS`). |
| correlationId | <code>string</code> | Correlation Id to add to the request. |
| options | <code>object</code> | Options associated with the call. Use to pass `metrics` to `rpRetry`. |

<a name="module_public-helper--module.exports..setSettings"></a>

#### module.exports~setSettings(settings, newConfig) ⇒ <code>object</code>
Set config.serverSettings with location data.

**Kind**: inner method of [<code>module.exports</code>](#exp_module_public-helper--module.exports)  
**Returns**: <code>object</code> - The updated config.serverSettings.  
**Category**: sync  

| Param | Type | Description |
| --- | --- | --- |
| settings | <code>object</code> | The config.serverSettings to update. Expected shape: `{ ip: { public, local }, public: { location } }`. |
| newConfig | <code>object</code> | The location configuration. Expected shape: `{ ip, localIp, location, instanceId }`. |