Docs / Reference

a9script authoring pack — crypto functions

The crypto functions, with their arguments and a line of real script each. Called by bare name; nothing is imported. A call marked pauses does real work outside the script: the run is saved, and continues on the next line with the result.

This is one part of the authoring pack — how a script is executed at all is the model part, and the other groups of functions are parts of their own. All of them are named at the end.

Generated — do not edit. Every block of script below is executed by the platform’s own test suite, and every error message is the one the platform produces today, so none of this can be what was true when someone last wrote it down.

uuid() — pauses

A fresh identifier, version 4, from real randomness. The value is kept the moment it is drawn, so a run that is saved and continued answers the same id — which is what makes it safe as an idempotency key for a call you must not make twice.

Answers: The identifier as text, e.g. f81d4fae-7dec-4d0e-a765-00a0c91e6bf6.

const key = uuid();
log("idempotency key " + key);

randomHex(bytes?) — pauses

Random bytes, written as hexadecimal — for a one-off token or a nonce. Real randomness, kept the moment it is drawn, exactly like uuid().

• bytes (number, optional) — How many bytes, from 1 to 1024. Defaults to 16.

Answers: Lower-case hexadecimal — two characters per byte, so 32 characters by default.

const nonce = randomHex(8);
log("nonce " + nonce);

sha256(text) — pauses

The SHA-256 digest of a piece of text, read as UTF-8 — the same digest every other system computes for the same string.

• text (string) — The text to hash.

Answers: The digest as lower-case hexadecimal, 64 characters.

const digest = sha256(input.event.body.id);
log("digest " + digest);

hmacSha256(key, message) — pauses

Signs a message with a shared secret (HMAC-SHA-256) — the shape webhook signatures use, so this is how a script proves a payload came from it. To CHECK an incoming signature, configure the endpoint’s own signature check instead: it runs before the script and compares in constant time, which === in a script does not.

• key (string) — The shared secret, as text.
• message (string) — What to sign, read as UTF-8.

Answers: The signature as lower-case hexadecimal, 64 characters.

const signature = hmacSha256(input.settings.signingSecret, input.event.body.id);
log("signature " + signature);

The rest of this pack

The page above is everything that is true only HERE. Ask for these parts by name for the rest:

• model — how a script is executed, the shape of its input, the rules enforced while it runs, and the mistakes that do not work here.
• functions-core — the core functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-encoding — the encoding functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-text — the text functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-number — the numbers functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-structured — the structured data functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-document — the documents functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-markdown — the markdown functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-datetime — the date & time functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-email — the email functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-blob — the files functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-mapping — the mapping functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-dataset — the datasets functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-state — the state functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-pagination — the pagination functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-control — the run control functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-functions — the config functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• mistakes — the habits from general JS that do not work here — each with the exact error it produces and the shape to write instead.
• standard-library — every built-in the language itself provides — JSON, Math, Object, String, Array, Number, Map, Set, Date, RegExp and the bare globals — one line each, with an example and its answer.