> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/scripting/globals/tools.md).

# Utility globals

Reference of the small global helpers available in scripts - ensureLatin, toDateTime, sleep, CryptoJS.HmacSHA256 and console.

Besides `fetch`, scripts have a handful of small global helpers for situations that come up in nearly every integration: cleaning text before it is sent to a system that only accepts Latin letters, turning a date string into a date the platform understands, waiting, signing a message and writing to the log. They are globals, so no import is needed.

<details>

<summary><strong>Real-world examples</strong></summary>

* A script normalizes the name of a customer to plain Latin letters before sending it to a ticketing system that rejects other alphabets.
* A pass data provider converts a birth date received as text into a date, and writes it back on the account.
* A script signs the payload sent to a partner webhook with a shared secret.
* A handler reports an unexpected remote answer with `console.warn`, so that it can be found in **Settings → Monitoring → Logs**.

</details>

## ensureLatin

Some external systems accept only the basic Latin alphabet, while customers type names with full-width letters, Cyrillic or Greek letters that look like Latin ones, mathematical "fancy" letters, or accents. `ensureLatin` replaces such characters by the plain ASCII letter they resemble.

```js
ensureLatin("Ｊｏｈｎ");   // "John"
ensureLatin("Zoé Müller");  // "Zoe Muller"
ensureLatin("山田", "?");    // "??" - no look-alike for these characters, so the replacement is used
```

The rules, in the order in which they apply to each character:

1. A character found in the look-alike table becomes its base ASCII letter. The table covers full-width letters, Greek and Cyrillic letters that look like Latin letters, mathematical alphanumeric letters and accented Latin letters, for both upper and lower case. Digits and punctuation look-alikes are not in the table.
2. Any other character outside ASCII becomes `replacement` when the second argument is given, and is kept unchanged when it is not.
3. ASCII characters are always kept.

Accented letters are mapped to their base letter, so two different names can end up identical after the call (for example `Müller` and `Muller`): do not use the result as a unique key.

A `null`, `undefined` or empty value is returned as it is, so the function can be applied to an optional field without a check. The function does not trim, change the case or remove symbols.

## toDateTime

The platform works with real date values, while scripts often hold dates as text. `toDateTime` converts a value to a date and normalizes it to UTC.

| Argument              | Result                                                                                                          |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `undefined` or `null` | `null`                                                                                                          |
| a string              | The string parsed with the culture of the server, then converted to UTC. A string that cannot be parsed throws. |
| a JavaScript `Date`   | The same moment in UTC.                                                                                         |
| anything else         | `null`, and a warning is logged.                                                                                |

The returned value is a platform date, not a JavaScript `Date`, so it is meant to be assigned to a field that expects a date, not to be used with JavaScript date arithmetic. Since a string is parsed with the culture of the server, an ambiguous text such as `03/04/2026` can be read as March 4 or as April 3. Scripts should pass ISO 8601 strings (`2026-04-03` or `2026-04-03T10:30:00Z`), which are unambiguous. A string without an offset is treated as a local time of the server before the conversion to UTC; adding the offset (`Z` or `+02:00`) removes the doubt.

```js
entity.birthDate = toDateTime(profile.birthDate);
```

## sleep

`sleep(ms)` returns a promise that resolves after `ms` milliseconds. It must be awaited.

```js
await sleep(500);
```

A script runs inside the request or job that triggered it, so a wait delays that request or job. The helper is meant for short pauses, for example to respect the pace of a remote system between two calls. Waiting for a condition in a loop is not a good pattern: a loop that never ends blocks the request. For rate limits, the `Throttle` option of [`fetch`](https://docs.thewalletcrew.io/developers-guides/scripting/globals/fetch.md) is the better tool.

## CryptoJS.HmacSHA256

`CryptoJS.HmacSHA256(secret, value)` computes an HMAC with SHA-256, with both arguments read as UTF-8 text, and returns the signature as hexadecimal text in uppercase. It is the only function of `CryptoJS` that exists.

Two differences with the library of the same name matter. The arguments are in the order **secret, then value**, whereas the original library takes the message first. The output is an uppercase hexadecimal string, not an object that needs `toString()`. Systems that expect lower case hexadecimal or Base64 need the script to convert the text (`toLowerCase()` for the former).

A typical use is to sign a payload for a partner webhook. The secret comes from [`getSecret`](https://docs.thewalletcrew.io/developers-guides/scripting/modules/secrets.md), never from the script text.

```js
import { getSecret } from "twc/secrets";

async function postSigned(url, payload) {
  const body = JSON.stringify(payload);
  const signature = CryptoJS.HmacSHA256(await getSecret("WEBHOOK-SIGNING-KEY"), body);

  return fetch(url, {
    Method: "POST",
    Headers: { "Content-Type": "application/json", "X-Signature": signature.toLowerCase() },
    Body: body
  });
}
```

The body is passed to `fetch` as the same string that was signed. Passing the object instead would serialize it a second time, and a different key order or spacing would make the signature invalid on the receiving side.

## console

`console` writes to the platform's log. The level of the method decides whether the line is recorded.

| Method                                                      | Level       |
| ----------------------------------------------------------- | ----------- |
| `console.log`, `console.debug`, `console.table`             | Debug       |
| `console.info`, `console.trace`                             | Information |
| `console.warn`, `console.assert` (when the assertion fails) | Warning     |
| `console.error`                                             | Error       |

In the default production configuration, Debug lines are not recorded. A script that must leave a trace uses `console.info`, `console.warn` or `console.error`. Lines at Information level and above appear in **Settings → Monitoring → Logs** (Application logs) for users with the insights permission. Logging therefore requires discipline. A log line must not contain a secret, a token, or personal data such as an email address or a whole API response; an identifier and a status code are enough to investigate.

```js
if (res.StatusCode !== 200) {
  console.warn("Loyalty lookup answered " + res.StatusCode + " for pass " + passId);
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/scripting/globals/tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
