# UTILS JavaScript API

## Connector functions UTILS JS API guide

In this javascript code, there are helper operations available to help users who are building their own functions. We will explain them below.

## JS UTILS API

These operations are grouped by their topic, at this time the available areas are:
- AT commands
- Endesa commands
- ODM commands
- Time commands

#### utils.atcmd.toDBm(value)

Translates the response got by the 'AT+CSQ' command, which is the GSM signal strength and a numerical value, to its corresponding dBm value.

**Kind**: global function  
**Returns**: The translation to dBm value 

| Param   | Type   | Description                |
|---------|--------|----------------------------|
| value   | number | The GSM signal strength.   |

Example of use:

```javascript
var dbVal = utils.atcmd.toDBm(1234);
```

#### utils.endesa.torscp(value)

| Param  | Type     | Description                  |
| ------ |----------|------------------------------|
| value | string   | value to be converted   |

Example of use:

```javascript
var val = utils.endesa.torscp("1234");
```

#### utils.endesa.toDbmPlusQuality(value)

| Param  | Type     | Description                  |
| ------ |----------|------------------------------|
| value | string   | value to be converted   |

Example of use:

```javascript
var val = utils.endesa.toDbmPlusQuality("1234");
```

#### utils.endesa.prepareMsisdn(msisdn)

If msisdn starts with "34", then returns the value without "34".
**Kind**: global function  
**Returns**: returns msisdn parameter without format

| Param  | Type     | Description                  |
| ------ |----------|------------------------------|
| msisdn | string   | msisdn to be converted   |


Example of use:

```javascript
var newMsisdn = utils.endesa.prepareMsisdn("341234567890");
//newMsisdn will be: 1234567890
```

#### utils.endesa.commandFrom(command)

Depending on the command value, specific translation will be returned.

**Kind**: global function  
**Returns**: returns msisdn parameter without format

| Param   | Type     | Description                |
|---------|----------|----------------------------|
| command | string   | command to be translated   |

Example of use:

```javascript
var newCommand = utils.endesa.commandFrom("9600;8E1");
//newCommand will be: ATS37=9S13=1\r\n
```

#### utils.odm.addValueToContext(key,value)

**Kind**: global function  


| Param  | Type     | Description                  |
| ------ |----------|------------------------------|
| key | string   | key to be added to context   |
| value | string   | value to be added to context |

Example of use:

```javascript
utils.odm.addValueToContext("key", "value");
```

#### utils.odm.sleep(time)

Sleeps for specified time

| Param  | Type     | Description                  |
| ------ |----------|------------------------------|
| time | number   | time to sleep in milliseconds |

Example of use:

```javascript
utils.odm.sleep(1000);
```

#### utils.odm.encryptString(originalValue, datastreamConfiguration, organizationName)

Encrypt an original string with the configuration established by the datastream of the organization

**Kind**: global function  
**Returns**: The originalValue encrypted 

| Param                   | Type    | Description                                                                                                                     |
|-------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------|
| originalValue           | string  | The value to encrypt.                                                                                                           |
| datastreamConfiguration | string  | The datastream of provision type, of the datamodel that define this value. This datastream has the configuration of encryption. |
| organizationName        | string  | The organization name to which the datamodel belongs.                                                                         |

Example of use:

```javascript
var encryptedValue = utils.odm.encryptString("originalValue", "datastreamConfiguration", "organizationName");
```

#### utils.odm.decryptString(encryptedValue, datastreamConfiguration, organizationName)

Decrypt an encrypted string with the configuration established by the datastream of the organization

**Kind**: global function  
**Returns**: The encryptedValue decrypted 

| Param                   | Type    | Description                                                                                                                     |
|-------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------|
| encryptedValue          | string  | The encrypted value to decrypt.                                                                                                 |
| datastreamConfiguration | string  | The datastream of provision type, of the datamodel that define this value. This datastream has the configuration of encryption. |
| organizationName        | string  | The organization name to which the datamodel belongs.                                                                         |

Example of use:

```javascript
var decryptedValue = utils.odm.decryptString("encryptedValue", "datastreamConfiguration", "organizationName");
```

#### utils.odm.getAddressTypeFromAddress(address)

Calculates the address type from a given address

**Kind**: global function  
**Returns**: The address type 

| Param    | Type     | Description                                          |
|----------|----------|------------------------------------------------------|
| address  | string   | The address which the type will be calculated for.   |

Example of use:

```javascript
var addressType = utils.odm.getAddressTypeFromAddress("[IP_ADDRESS]");
//addressType will be: ipv4

var addressType = utils.odm.getAddressTypeFromAddress("2001:0db8:85a3:0000:0000:8a2e:0370:7334");
//addressType will be: ipv6
```

<a name="entitiesValue"></a>

#### utils.odm.entitiesValue(entities, datastream, index)

Extract from the first entity of entities array specified datastream "value" field value.

**Kind**: global function  
**Returns**: \* - Specified datastream "value" field. It can be complex object. null if datastream does not exist.  

| Param      | Type   | Description                                                                                          |
| ---------- |--------|------------------------------------------------------------------------------------------------------|
| entities   | Array  | Array of objects with flattened entity.                                                              |
| datastream | String | Datastream name, for example: 'provision.device.identifier'.                                         |
| index      | number | Array Index. If provided datastream is an array (i.e. comm module), element index must be specified. |

Example of use:

```javascript
var value = utils.odm.entitiesValue(entities, "provision.device.identifier", 0);
```

<a name="httpRequest"></a>

#### utils.odm.httpRequest(request, payload)

Executes specified request with specified payload.

**Kind**: global function  
**Returns**: Object - JSON with response. It will have two fields: 'statusCode' with http result code and 'body' with response body content.  

| Param   | Type     | Description                                                                                                                                                                   |
| ------- |----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| request | Object   | Object with requests parameters: 'method', 'uri' and 'headers'.    - 'method': GET, POST, PUT, DELETE.   - 'uri': request uri.   - 'headers': json with http request headers. |
| payload | \*       | data to be sent. It can be null.                                                                                                                                              |

Example of use:

```javascript
var response = utils.odm.httpRequest({method: "GET", uri: "http://example.com", headers: {}}, null);
```

#### utils.date.period.previousQuarter(referenceTimeMillis)

Calculates previous quarter from specified time in milliseconds.

**Kind**: global function  
**Returns**: return an object with initial and final times of defined period

| Param                 | Type     | Description                       |
| --------------------- | -------- | ---------------------------------|
| referenceTimeMillis   | number   | reference time in milliseconds    |


Example of use:

```javascript
var period = utils.date.period.previousQuarter(1698841200000);//2023-11-01 12:20:00
```

It will return:

```json
{
    "initial": 1698840000000, //2023-11-01 12:00:00:000
    "final": 1698840899000, //2023-11-01 12:14:59:999
    "type": "previousQuarter" 
}
```

#### utils.date.period.previousDay(referenceTimeMillis)

Calculates previous day from specified time in milliseconds.

**Kind**: global function  
**Returns**: return an object with initial and final times of defined period

| Param                 | Type     | Description                       |
| ------                |----------| ----------------------------------|
| referenceTimeMillis   | number   | reference time in milliseconds    |


Example of use:

```javascript
var period = utils.date.period.previousDay(1698841200000);//2023-11-01 12:20:00
```

It will return:

```
{
    "initial": 1698840000000, //2023-10-31 00:00:00:000
    "final": 1698840899000, //2023-10-31 23:59:59:999
    "type": "previousDay" 
}
```


#### utils.date.period.previousWeek(referenceTimeMillis)

Calculates previous week from specified time in milliseconds.

**Kind**: global function  
**Returns**: return an object with initial and final times of defined period

| Param                 | Type   | Description                       |
| ------                |--------| ----------------------------------|
| referenceTimeMillis   | number | reference time in milliseconds    |

Example of use:

```javascript
var period = utils.date.period.previousWeek(1698841200000);//2023-11-01 12:20:00 (Wednesday)
```

It will return:

```json
{
    "initial": 1698840000000, //2023-10-23 00:00:00:000 (Monday)
    "final": 1698840899000, //2023-10-29 23:59:59:999 (Sunday)
    "type": "previousWeek" 
}
```

#### utils.date.period.previousMonth(referenceTimeMillis)

Calculates previous month from specified time in milliseconds.

**Kind**: global function  
**Returns**: return an object with initial and final times of defined period

| Param                 | Type     | Description                       |
| ------                |----------| ----------------------------------|
| referenceTimeMillis   | number   | reference time in milliseconds    |


Example of use:

```javascript
var period = utils.date.period.previousMonth(1698841200000);//2023-11-01 12:20:00
```

It will return:

```json
{
    "initial": 1698840000000, //2023-10-01 00:00:00:000
    "final": 1698840899000, //2023-10-31 23:59:59:999
    "type": "previousMonth" 
}
```

#### utils.date.period.customPeriodUtc(initialTimeStr, finalTimeStr)

Calculates specified period in utc times in milliseconds.

**Kind**: global function  
**Returns**: return an object with initial and final times of defined period

| Param                  | Type    | Description                       |
|------------------------|---------| ----------------------------------|
| referenceTimeMillis    | number  | reference time in milliseconds    |

Example of use:

```javascript
var period = utils.date.period.customPeriodUtc("2011-11-01T14:20:00.000+0100","2011-11-01T14:25:00.000+0100");
```

It will return:

```
{
    "initial": 1698844800000, //2011-11-01T13:20:00.000
    "final": 1698845100000, //2011-11-01T13:25:00.000
    "type": "custom" 
}
```

#### utils.date.period.lastMinutes(minutes, referenceTimeMillis)

Calculates a period of defined minutes until reference time. If referenceTimeMillis is not defined, current time will be used as reference

**Kind**: global function  
**Returns**: return an object with initial and final times of defined period

| Param               | Type     | Description                    |
|---------------------|----------|--------------------------------|
| minutes             | number   | number of minutes of period    |
| referenceTimeMillis | number   | reference time in milliseconds |


Example of use:

```javascript
var period = utils.date.period.lastMinutes(15, 1698841200000);//2023-11-01 12:20:00
```

It will return:

```json
{
    "initial": 1698840000000, //2023-11-01 12:05:00:000
    "final": 1698841200000, //2023-11-01 12:20:00:000
    "type": "lastMinutes" 
}
```

#### utils.date.period.lastHours(hours, referenceTimeMillis)

Calculates a period of defined hours until reference time. If referenceTimeMillis is not defined, current time will be used as reference

**Kind**: global function  
**Returns**: return an object with initial and final times of defined period

| Param                | Type     | Description                      |
|----------------------|----------|----------------------------------|
| hours                | number   | number of hours of period        |
| referenceTimeMillis  | number   | reference time in milliseconds   |

Example of use:

```javascript
var period = utils.date.period.lastHours(24, 1698841200000);//2023-11-01 12:20:00
```

It will return:

```
{
    "initial": 1698840000000, //2023-10-31 12:20:00:000
    "final": 1698841200000, //2023-11-01 12:20:00:000
    "type": "lastHours" 
}
```

#### utils.date.period.lastDays(days, referenceTimeMillis)

Calculates a period of defined days until reference time. If referenceTimeMillis is not defined, current time will be used as reference

**Kind**: global function  
**Returns**: return an object with initial and final times of defined period

| Param                | Type      | Description                    |
|----------------------|-----------|--------------------------------|
| days                 | number    | number of hours of period      |
| referenceTimeMillis  | number    | reference time in milliseconds |


Example of use:

```javascript
var period = utils.date.period.lastDays(7, 1698841200000);//2023-11-01 12:20:00
```

It will return:

```
{
    "initial": 1698840000000, //2023-10-25 12:20:00:000
    "final": 1698841200000, //2023-11-01 12:20:00:000
    "type": "lastDays" 
}
```

#### utils.bytes.fromHexString(hexString)

**Kind**: global function  
**Returns**: return an <code>Uint8Array</code> object equivalent to de hexadecimal String

| Param                 | Type                | Description                    |
| ------                |---------------------|--------------------------------|
| hexString             | <code>string</code> | String in hexadecimal format   |

Example of use:

```javascript
var bytes = utils.bytes.fromHexString("09 4A 48")
```

It will return:

```json
[09, 74, 72]
```

#### utils.bytes.toHexString(array)

**Kind**: global function  
**Returns**: return the hexadecimal string representation.

| Param | Type                        | Description                       |
|-------|-----------------------------|-----------------------------------|
| array | <code>Array of bytes</code> | hexadecimal string representation |


Example of use:

```javascript
var hexStr = utils.bytes.toHexString([09, 74, 72])
```

It will return:

```json
"094A48"
```

#### utils.bytes.fromText(str)

**Kind**: global function  
**Returns**: return the <code>Uint8Array</code> representation of the string with UTF encoding.

| Param | Type                | Description |
|-------|---------------------|-------------|
| str   | <code>string</code> | any text    |

Example of use:

```javascript
var bytes = utils.bytes.fromText("Hello!")
```

It will return:

```json
[72, 101, 108, 108, 111, 33]
```

#### utils.bytes.toText(bytes)

**Kind**: global function  
**Returns**: return the <code>string</code> representation of array of bytes in UTF.

| Param | Type                        | Description                      |
|-------|-----------------------------|----------------------------------|
| bytes | <code>Array of bytes</code> | bytes representing a text in UTF |


Example of use:

```javascript
var text = utils.bytes.toText([72, 101, 108, 108, 111, 33])
```

It will return:

```json
"Hello!"
```