# MESA SDK

vendor/Mesa.js

## Mesa.log.info(message\[, meta])

Log info to Mesa Logs.

**Parameters**

| Name    | Type     | Description |            |
| ------- | -------- | ----------- | ---------- |
| message | `string` |             |            |
| meta    | `object` |             | *Optional* |

## Mesa.log.warn(message\[, meta])

Log a warning to Mesa Logs.

**Parameters**

| Name    | Type     | Description |            |
| ------- | -------- | ----------- | ---------- |
| message | `string` |             |            |
| meta    | `object` |             | *Optional* |

## Mesa.log.error(message\[, meta])

Log an error to Mesa Logs.

**Parameters**

| Name    | Type     | Description |            |
| ------- | -------- | ----------- | ---------- |
| message | `string` |             |            |
| meta    | `object` |             | *Optional* |

## Mesa.log.debug(message\[, meta])

Log info to Mesa Logs only if the Automation is in Debug Mode.

**Parameters**

| Name    | Type     | Description |            |
| ------- | -------- | ----------- | ---------- |
| message | `string` |             |            |
| meta    | `object` |             | *Optional* |

## Mesa.request.get(path, options)

Make a GET request to an external Rest API.

**Parameters**

| Name    | Type                                     | Description |   |
| ------- | ---------------------------------------- | ----------- | - |
| path    | `string`                                 |             |   |
| options | [RequestOptions](#object-requestoptions) |             |   |

**Returns**

* [Response](#object-or-string-response)

## Mesa.request.post(path, data, options)

Make a POST request to an external Rest API.

**Parameters**

| Name    | Type                                     | Description |   |
| ------- | ---------------------------------------- | ----------- | - |
| path    | `string`                                 |             |   |
| data    | `object`                                 |             |   |
| options | [RequestOptions](#object-requestoptions) |             |   |

**Returns**

* [Response](#object-or-string-response)

## Mesa.request.put(path, data, options)

Make a PUT request to an external Rest API.

**Parameters**

| Name    | Type                                     | Description |   |
| ------- | ---------------------------------------- | ----------- | - |
| path    | `string`                                 |             |   |
| data    | `object`                                 |             |   |
| options | [RequestOptions](#object-requestoptions) |             |   |

**Returns**

* [Response](#object-or-string-response)

## Mesa.request.patch(path, data, options)

Make a PATCH request to an external Rest API.

**Parameters**

| Name    | Type                                     | Description |   |
| ------- | ---------------------------------------- | ----------- | - |
| path    | `string`                                 |             |   |
| data    | `object`                                 |             |   |
| options | [RequestOptions](#object-requestoptions) |             |   |

**Returns**

* [Response](#object-or-string-response)

## Mesa.request.delete(path, options)

Make a DELETE request to an external Rest API.

**Parameters**

| Name    | Type                                     | Description |   |
| ------- | ---------------------------------------- | ----------- | - |
| path    | `string`                                 |             |   |
| options | [RequestOptions](#object-requestoptions) |             |   |

**Returns**

* [Response](#object-or-string-response)

## Mesa.request.send(method, path, data, options)

Make a request to an external Rest API.

**Parameters**

| Name    | Type                                     | Description                                       |   |
| ------- | ---------------------------------------- | ------------------------------------------------- | - |
| method  | `string`                                 | One of `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` |   |
| path    | `string`                                 |                                                   |   |
| data    | `object`                                 |                                                   |   |
| options | [RequestOptions](#object-requestoptions) |                                                   |   |

**Returns**

* [Response](#object-or-string-response)

## Mesa.request.base64\_encode(string)

Base-64 encode a string. This is helpful when building an `Authorization` header for basic auth requests.

**Parameters**

| Name   | Type     | Description          |   |
| ------ | -------- | -------------------- | - |
| string | `string` | The string to encode |   |

**Returns**

* `string` The base-64 encoded version of the input string parameter.

## Mesa.request.base64\_decode(string\[, strict])

Base64 decode a string. Decodes data encoded with MIME base64

**Parameters**

| Name   | Type     | Description                                                                                                                                                                      |            |
| ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| string | `string` | The base-64 encoded version of the input string parameter.                                                                                                                       |            |
| strict | `bool`   | If the strict parameter is set to TRUE then the base64\_decode() function will return FALSE if the input contains character from outside the base64 alphabet. Defaults to FALSE. | *Optional* |

**Returns**

* `string` The decoded string.

## Mesa.request.hash(algorithm, string\[, base64encode])

Generate a hash of a string. This is helpful when creating signed requests.

**Parameters**

| Name         | Type     | Description                                            |            |
| ------------ | -------- | ------------------------------------------------------ | ---------- |
| algorithm    | `string` | The algorithm to use. Options: `sha1`, `sha256`, `md5` |            |
| string       | `string` | The string to create the hash from                     |            |
| base64encode | `string` | Should we base64-encode the raw value of the hash?     | *Optional* |

**Returns**

* `string` The raw binary data of the hash

## Mesa.request.hashHmac(algorithm, string, string\[, base64encode])

Generate a keyed hash value using the HMAC method. This is helpful when creating signed requests.

**Parameters**

| Name         | Type     | Description                                                                  |            |
| ------------ | -------- | ---------------------------------------------------------------------------- | ---------- |
| algorithm    | `string` | The algorithm to use. Options: `sha1`, `sha256`, `md5`                       |            |
| string       | `string` | The string to create the hash from                                           |            |
| string       | `string` | Shared secret key used for generating the HMAC variant of the message digest |            |
| base64encode | `string` | Should we base64-encode the raw value of the hash?                           | *Optional* |

**Returns**

* `string` The raw binary data of the hash

## Mesa.request.sleep($seconds)

Pauses execution

**Parameters**

| Name     | Type  | Description |   |
| -------- | ----- | ----------- | - |
| $seconds | `int` |             |   |

**Returns**

*

## Mesa.credential.get(key\[, defaultValue])

Get a secret.

**Parameters**

| Name         | Type     | Description                                                                                                                                       |            |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| key          | `string` |                                                                                                                                                   |            |
| defaultValue | `string` | A default value to use if the secret cannot be found. If `defaultValue` is empty, the script will throw a fatal error if the secret is not found. | *Optional* |

**Returns**

* `string` The secret value.

## Mesa.credential.set(key, value\[, options])

Save a secret value.

**Parameters**

| Name                    | Type     | Description                                                                                    |            |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------- | ---------- |
| key                     | `string` | The credential key or id.                                                                      |            |
| value                   | `string` | The value to save. This will be encrypted at rest, and can contained a stringified JSON array. |            |
| options                 | `object` |                                                                                                | *Optional* |
| options.oauth\_provider | `bool`   |                                                                                                | *Optional* |
| options.oauth\_scope    | `object` |                                                                                                | *Optional* |
| options.trigger\_type   | `object` |                                                                                                | *Optional* |

## Mesa.database.query(sql)

Get a storage item

**Parameters**

| Name | Type     | Description          |   |
| ---- | -------- | -------------------- | - |
| sql  | `string` | The SQL query to run |   |

**Returns**

* `array` The result of the query.

## Mesa.storage.get(key\[, defaultValue])

Get a storage item

**Parameters**

| Name         | Type     | Description                                                                                                                                                 |            |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| key          | `string` |                                                                                                                                                             |            |
| defaultValue | `string` | A default value to use if the storage key cannot be found. If `defaultValue` is empty, the script will throw a fatal error if the storage key is not found. | *Optional* |

**Returns**

* `string` The storage value.

## Mesa.storage.set(key, value)

Get a storage item

**Parameters**

| Name  | Type     | Description |   |
| ----- | -------- | ----------- | - |
| key   | `string` |             |   |
| value | `string` |             |   |

## Mesa.liquid.render(template, params)

Render a liquid template with the `params` passed.

**Parameters**

| Name     | Type     | Description                              |   |
| -------- | -------- | ---------------------------------------- | - |
| template | `string` | String representing a liquid template.   |   |
| params   | `object` | A keyed object of parameters to replace. |   |

**Returns**

* `string` The rendered template code.

## Mesa.input.getWebhookUrl(type, format, automationId, key)

Generates the URL for input webhooks

**Parameters**

| Name         | Type     | Description                                                                                                                                         |   |
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| type         | `string` | Type of webhook: `json`, `shopify`                                                                                                                  |   |
| format       | `string` | Format of the returned data: `string` or `array`. If string, a full URL is returned. If `array`, URL will comprise two fields `suffix` and `prefix` |   |
| automationId | `string` | ID of the Automation                                                                                                                                |   |
| key          | `string` | The key of the trigger                                                                                                                              |   |

**Returns**

* `string` `array` The rendered template code.

## Mesa.output.next(payload, params)

Pass a payload to the service and call the next step in this Automation.

**Parameters**

| Name           | Type     | Description                                                                                     |            |
| -------------- | -------- | ----------------------------------------------------------------------------------------------- | ---------- |
| payload        | `object` |                                                                                                 |            |
| params         | `object` | Parameters to send to the output, such as tokens to construct a Shopify API url                 |            |
| params.enqueue | `bool`   | Defaults to false. Set to true if you are exploding multiple tasks that can be run in parallel. | *Optional* |

## Mesa.output.send(outputKey, payload, enqueue)

Call an arbitrary output from a Mesa Script

**Parameters**

| Name      | Type     | Description                                                                                     |   |
| --------- | -------- | ----------------------------------------------------------------------------------------------- | - |
| outputKey | `string` |                                                                                                 |   |
| payload   | `object` |                                                                                                 |   |
| enqueue   | `bool`   | Defaults to false. Set to true if you are exploding multiple tasks that can be run in parallel. |   |

## Mesa.automation.send(automationKey, payload)

Call another automation from a Mesa Script

**Parameters**

| Name          | Type     | Description                                                                                                                                                                            |   |
| ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| automationKey | `string` | In the form `${automationKey}`, this will trigger the first input in the Automation. In the form `${automationKey}/${inputKey}`, this will trigger a specific input in the automation. |   |
| payload       | `object` |                                                                                                                                                                                        |   |

## Mesa.ftp.deleteFile(filename)

Delete the file loaded by the Input.

**Parameters**

| Name     | Type     | Description                               |   |
| -------- | -------- | ----------------------------------------- | - |
| filename | `string` | Typically passed from `context.filename`. |   |

## Mesa.ftp.moveFile(filename, destinationFilenameAndPath)

Move the file loaded by the Input to a new location.

**Parameters**

| Name                       | Type     | Description                               |   |
| -------------------------- | -------- | ----------------------------------------- | - |
| filename                   | `string` | Typically passed from `context.filename`. |   |
| destinationFilenameAndPath | `string` |                                           |   |

## Mesa.xml.decode(xmlString\[, namespaceSep='\_'])

Convert an XML file into an {object}. This function will condense XML namespaces into {namespaceSep = '\_'} separated values: <soapenv:Body> becomes { soapenv\_Body: {} }

**Parameters**

| Name              | Type     | Description                                                                     |            |
| ----------------- | -------- | ------------------------------------------------------------------------------- | ---------- |
| xmlString         | `string` | The xml file to be decoded                                                      |            |
| namespaceSep='\_' | `string` | Namespace separator for replacing <soapenv:Body> type values with soapenv\_Body | *Optional* |

**Returns**

* `object`

## Mesa.xml.encode(xmlObject\[, wrapReplace, namespaceSep='\_'])

Convert an object into an XML string.

**Parameters**

| Name              | Type     | Description                                                                    |            |
| ----------------- | -------- | ------------------------------------------------------------------------------ | ---------- |
| xmlObject         | `object` | The object to be turned into xml.                                              |            |
| wrapReplace       | `string` | Replace the default wrapping provided with another value                       | *Optional* |
| namespaceSep='\_' | `string` | Namespace separator for replacing soapenv\_Body: {} values with <soapenv:Body> | *Optional* |

**Examples**

```javascript
// returns <?xml version="1.0" encoding="UTF-8"?><doc>\n  <book>\n ...
Mesa.xml.encode({ book: { ... }});
```

```javascript
// returns <?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">\n  <soapenv:Body>\n ...
Mesa.xml.encode({ soapenv_Body: { ... } }, '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">');
```

**Returns**

* `string`

## Mesa.xml.valid(xmlString)

Check if xml is valid

**Parameters**

| Name      | Type     | Description |   |
| --------- | -------- | ----------- | - |
| xmlString | `string` |             |   |

**Examples**

```javascript
// returns true
Mesa.xml.valid('<?xml version="1.0" encoding="UTF-8"?><doc><book><Name>My Book</Name></book></doc>');
```

```javascript
// throws error about namespace
Mesa.xml.valid('<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope><book><Name>My Book</Name></book></soapenv:Envelope>');
```

**Returns**

* `bool`

## Mesa.csv.decode(data\[, returnObject, options])

Convert a CSV file into an object. Keys will be matched from the first header row of the CSV file.

**Parameters**

| Name                  | Type     | Description                                                                                                                   |            |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------- |
| data                  | `string` |                                                                                                                               |            |
| returnObject          | `bool`   | Defaults to `true`, which will return an object keyed by the first row in the CSV content. Set to `false` to return an array. | *Optional* |
| options               | `object` |                                                                                                                               | *Optional* |
| options.delimiter=',' | `string` | The delimiter to use when parsing the CSV file. Must be a single character.                                                   | *Optional* |

**Returns**

* `object` `array`

## Mesa.csv.encode(data\[, headerRow])

Convert an object a CSV string.

**Parameters**

| Name      | Type     | Description                                                                   |            |
| --------- | -------- | ----------------------------------------------------------------------------- | ---------- |
| data      | `object` |                                                                               |            |
| headerRow | `bool`   | Defaults to `true`. Set to `false` to skip the header row when returning CSV. | *Optional* |

**Returns**

* `string`

## Mesa.vo.push(outputKey, payload)

Push to a Virtual Output.

**Parameters**

| Name      | Type     | Description |   |
| --------- | -------- | ----------- | - |
| outputKey | `string` |             |   |
| payload   | `mixed`  |             |   |

## Mesa.vo.clear(outputKey)

Mark the matching Virtual Output records as cleared by the current Mesa Script.

**Parameters**

| Name      | Type     | Description |   |
| --------- | -------- | ----------- | - |
| outputKey | `string` |             |   |

## Mesa.vo.clearOne(outputKey, mesaId)

Mark a single Virtual Output record as cleared by the current Mesa Script.

**Parameters**

| Name      | Type     | Description                                                                 |   |
| --------- | -------- | --------------------------------------------------------------------------- | - |
| outputKey | `string` |                                                                             |   |
| mesaId    | `string` | The ID of the record to clear (returned as mesa\_id in the Virtual Output). |   |

## Mesa.date.setTimezone(timezone)

Set the timezone to use to execute all script commands.

**Parameters**

| Name     | Type     | Description                                                                                                                                                      |   |
| -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| timezone | `string` | The timezone identifier, like UTC or America/Los\_Angeles. [See a full list of TZ Database names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). |   |

**Returns**

* `string` The timezone identifier, like UTC or Europe/Lisbon.

## {Object} RequestOptions()

Request options

**Parameters**

| Name                            | Type     | Description                                                                                                                                   |            |
| ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| json                            | `bool`   | Automatically add JSON Content-Type headers and decode the response. Defaults to `true`.                                                      | *Optional* |
| query                           | `object` | Parameters to append to the querystring.                                                                                                      |            |
| headers                         | `object` | Headers to send to the request.                                                                                                               |            |
| debug                           | `bool`   | Log request information and response headers. Defaults to `context.automation.debug` (`false`).                                               | *Optional* |
| skipJsonWrap                    | `bool`   | Skip the named auto wrapping of outgoing data. Defaults to `false`.                                                                           | *Optional* |
| include\_headers                | `bool`   | Include headers in the response. The response format will be [ResponseRaw](#object-responseraw).                                              | *Optional* |
| options.debug\_exclude\_headers | `array`  | Exclude headers from debugging information to keep secret keys a secret. An array of header keys (example: `Content-Type`).                   | *Optional* |
| stringify\_large\_ints          | `bool`   | If JSON response, and response has ints over the JS max int, will traverse entire payload and cast long ints to strings. Defaults to `false`. | *Optional* |

## {Object|String} Response()

Request response:

* [ResponseRaw](#object-responseraw) if `options.include_headers` is `true`,
* `object` if `options.json` is `true`,
* `string` if `options.json` is `false`.

## {Object} ResponseRaw()

Request response with headers when `options.include_headers` is `true`.

**Parameters**

| Name            | Type                                   | Description                                                 |   |
| --------------- | -------------------------------------- | ----------------------------------------------------------- | - |
| body            | [Response](#object-or-string-response) | Response from the server                                    |   |
| headers         | `object`                               | Headers to from response.                                   |   |
| request\_method | `string`                               | The method used to create the response: `GET`, `POST`, etc. |   |
| request\_url    | `string`                               | The URL used to create the response.                        |   |