Utilities

The scripting API provides various helper functions for common tasks including random number generation, text tokenization, timers, file operations, clipboard access, and configuration management.

Random Number Generation

The random API provides methods for generating random values. Math.random() is also available, but these are provided for convenience.

Random Boolean

Generate a random boolean value:

let coinFlip = api.v1.random.bool();
api.v1.log(`Coin flip: ${coinFlip ? 'heads' : 'tails'}`);

Random Integer

Generate a random integer within a range. The min and max values are inclusive:

// Random number between 1 and 6
let diceRoll = api.v1.random.int(1, 6);
api.v1.log(`Dice roll: ${diceRoll}`);

// Random number between 0 and 99
let percentage = api.v1.random.int(0, 99);

Random Float

Generate a random floating-point number. The min is inclusive, and the max is exclusive:

// Random number between min and max
let temperature = api.v1.random.float(0.5, 1.5);

Dice Roll Notation

Generate random numbers using standard dice notation:

// Roll 3 six-sided dice
let result = api.v1.random.roll('3d6');
api.v1.log(`Rolled: ${result.total}`);

// Roll 2d20 + 5
let attackRoll = api.v1.random.roll('2d20+5');

// Roll 2d6+1d4+3
let damageRoll = api.v1.random.roll('2d6+1d4+3');

Text Tokenization

The tokenizer API allows you to encode text into tokens and decode tokens back into text. This is useful for managing context length and for some generation parameters that require token ids.

Encoding Text to Tokens

Convert text into an array of token IDs:

let text = 'When did we get here?';
let tokens = await api.v1.tokenizer.encode(text, 'glm-4-6');
api.v1.log(`Token count: ${tokens.length}`);
api.v1.log(`Token IDs: ${tokens.join(', ')}`);

The tokenizer used will depend on the model specified. A model must be provided.

Decoding Tokens to Text

Convert token IDs back into text:

let tokens = [49955, 13];
let text = await api.v1.tokenizer.decode(tokens, 'glm-4-6');
api.v1.log(`Decoded text: ${text}`);

The timers API provides methods for scheduling delayed execution and creating pauses in your scripts. The standard setTimeout and clearTimeout functions are not available in the scripting environment, so these are provided as alternatives.

setTimeout

Execute a function after a delay:

let timeoutId = api.v1.timers.setTimeout(() => {
  api.v1.log('This runs after 2 seconds');
}, 2000);

The delay is specified in milliseconds. The function returns a timeout ID that can be used to cancel the timer.

clearTimeout

Cancel a scheduled timeout:

let timeoutId = api.v1.timers.setTimeout(() => {
  api.v1.log('This will never run');
}, 5000);

// Cancel the timeout
api.v1.timers.clearTimeout(timeoutId);

sleep

Pause script execution for a specified duration:

async function delayedAction() {
  api.v1.log('Starting...');
  
  await api.v1.timers.sleep(3000); // Wait 3 seconds
  
  api.v1.log('3 seconds later...');
}

The sleep function returns a promise that resolves after the specified delay.

UUID Generation

Generate unique identifiers for use in your scripts:

let uniqueId = api.v1.uuid();
api.v1.log(`Generated UUID: ${uniqueId}`);

File Operations

The file API provides methods for prompting users to select files and saving data to files. Keep in mind that this is browser-based file operations. There’s no direct access to the user’s file system. Users must select files manually, and no control over where files are saved.

Prompting for File Selection

Prompt the user to select a file. readAs can be ‘text’, ‘dataURL’, or ‘arrayBuffer’:

// Get a single file as an ArrayBuffer
let file = await api.v1.file.prompt({
  readAs: 'arrayBuffer'
});
if (file) {
  api.v1.log(`Content: ${file.byteLength}`);
}

Saving Files

Trigger a file download/save dialog with the specified data:

let data = JSON.stringify({ name: 'My Data', value: 42 }, null, 2);

await api.v1.file.save('file.json', data);

Only string data is supported for saving files.

Clipboard Access

Copy text to the user’s clipboard:

await api.v1.clipboard.writeText('This text is now on the clipboard!');
api.v1.ui.toast('Text copied to clipboard');