# 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.                        |   |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.getmesa.com/tools/custom-code/libraries/sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.