Aller au contenu principal

Référence de l'API de scripts

Hodor exécute vos scripts dans un moteur JavaScript intégré. Selon le type de script, Hodor appelle l'une des fonctions d'entrée ci-dessous au bon moment — vous n'implémentez que la logique dont vous avez besoin. Si vous ne modifiez rien, supprimez la fonction d'entrée inutilisée pour éviter des appels inutiles.

Objets et classes globaux disponibles :

CatégorieNoms
Fonctions d'entréeonRequest, onResponse, onSessionCompleted, onSchedule, abort()
Modules natifs $$codec, $hash, $hmac, $crypto, $jwt, $format, $fs, $env, $uuid, $log
API standard du Webfetch, HTTPClient, setTimeout / setInterval, btoa / atob / sleep / require / TextEncoder / crypto, console
Classes HTTPRequest, Response, Body, Headers, URLSearchParams
StockageSharedPreferences, variables sdk
ContextesRewriteContext, CompletedContext, ScheduleContext
astuce

Utilisez console.log(...) n'importe où dans un script pour inspecter des valeurs — la sortie apparaît dans la vue de logs du script.

Fonctions d'entrée​

Les scripts sont détectés en scannant les déclarations async function — le nombre de paramètres de chaque fonction d'entrée est fixe (onRequest/onResponse en prennent 3, onSessionCompleted en prend 4, onSchedule en prend 1). Les affectations de fonctions fléchées (let onRequest = async (...) => {}) ne sont pas détectées. Les noms de paramètres sont libres.

onRequest(context, url, request)​

Conçue pour les scripts de réécriture et les scripts de pré-requête Quick Request. Cette fonction est appelée avant que la requête HTTP soit envoyée au serveur. Retournez la request (éventuellement modifiée).

ParamètreTypeDescription
contextRewriteContextL'objet de contexte.
urlstringL'URL de la requête HTTP.
requestRequestL'objet de requête HTTP.
// modify request body
async function onRequest(context, url, request) {
// parse to Text
var text = request.body.parseText()
console.log(text)
request.body = "this is a replaced request text"

// parse to JSON
var json = request.body.parseJSON()
json["script_json"] = "JSONValue"
request.body = json

// parse to URLSearchParams
var urlencoded = request.body.parseURLSearchParams()
urlencoded.append("script", "parseURLSearchParams")
request.body = urlencoded
// Done
return request;
}
// redirect, modify path / queries / headers
async function onRequest(context, url, request) {
console.log(url);
// set a parameter, you can get it in onResponse
context.parameters["custom"] = "custom parameter on request"

// redirect
request.scheme = "http"
request.path = "/upload/json"
request.host = "192.168.3.30"
request.port = 6000
// change method
request.method = "POST"

// queries operation
request.queries.append("name", "value1") // add query
request.queries.set("name", "value2") // replace or add query
request.queries.get("name") // get query by name
request.queries.delete("name") // delete query by name

// headers operation
request.headers.delete("accept") // delete header by name
request.headers.append("hodor", "custom value") // add name-value pair
request.headers.forEach((value, name) => {
console.log(name + ":" + value)
});
// Done
return request;
}

onResponse(context, url, response)​

Conçue pour les scripts de réécriture et les scripts de post-réponse Quick Request. Cette fonction est appelée avant que la réponse HTTP soit renvoyée au client. Retournez la response (éventuellement modifiée).

ParamètreTypeDescription
contextRewriteContextL'objet de contexte.
urlstringL'URL de la réponse HTTP.
responseResponseL'objet de réponse HTTP.
// response body
async function onResponse(context, url, response) {
// parse to Text
var text = response.body.parseText()
console.log(text)
response.body = "this is a replaced response text"

// parse to JSON
var json = response.body.parseJSON()
json["script_json"] = "JSONValue"
response.body = json

// parse to URLSearchParams
var urlencoded = response.body.parseURLSearchParams()
urlencoded.append("script", "parseURLSearchParams")
response.body = urlencoded
// Done
return response;
}
// change status code and headers
async function onResponse(context, url, response) {
// get parameters set in onRequest
console.log(context.parameters["custom"]) // Output "custom parameter on request"

response.statusCode = 200 // change status code
response.statusPhrase = "OK" // change status phrase

response.headers.delete("accept")
response.headers.append("hodor", "custom value")
response.headers.forEach((value, name) => {
console.log(name + ":" + value)
});
// Done
return response
}

onSessionCompleted(context, url, request, response)​

Conçue pour le script HTTP Completed. Appelée de façon asynchrone après le retour de la réponse HTTP, sans affecter la transmission des données entre l'app et le serveur. Utile pour la collecte et le transfert de données.

ParamètreTypeDescription
contextCompletedContextL'objet de contexte.
urlstringL'URL de la requête HTTP.
requestRequestL'objet de requête HTTP.
responseResponseL'objet de réponse HTTP.
// sample: pass session data to your own server
async function onSessionCompleted(context, url, request, response) {
try {
var reqText = request.body.parseText();
var rspText = response.body.parseText()
var params = {
"body": { // HTTPClient post body data
"url": url, // request url
"reqHeader": request.headers.encode(), // request headers
"reqText": reqText, // request body
"rspHeader": response.headers.encode(), // response headers
"rspText": rspText, // response body
},
"headers": { // HTTPClient headers
"from": "onSessionCompleted"
},
}
const rsp = await HTTPClient.post("http://192.168.3.30:8000/upload", params)
let text = rsp.body.parseText()
console.log(text)
} catch(error) {
console.log(error)
}
}

onSchedule(context)​

Conçue pour le script planifié (Schedule Script). Appelée à l'heure de déclenchement planifiée (les expressions cron à 5 ou 6 champs sont prises en charge). Utilisez abort() pour arrêter la boucle planifiée.

ParamètreTypeDescription
contextScheduleContextL'objet de contexte.
async function onSchedule(context) {
// set custom parameters for next runloop
context.parameters["custom"] = "custom parameters for next runloop";
// repeated count
console.log(`repeatedCount ${context.repeatedCount}`);
// if repeatedCount is 2, abort schedule
if (context.repeatedCount == 2) {
abort()
}
// you can also use HTTPClient to send requests
const rsp = await HTTPClient.get("https://www.apple.com")
let text = rsp.body.parseText()
console.log(text)
}

abort()​

Dans les scripts de canal (onRequest / onResponse / onSchedule), appelez abort() pour arrêter le script et interrompre immédiatement l'exécution en cours — il lève une AbortError que Hodor vous signale.

// ✅ correct — abort() is injected into the script scope
async function onRequest(context, url, request) {
if (url.includes("/tracking")) abort();
return request;
}
attention

Ne déclarez surtout pas onRequest(context, url, request, aborter) avec un 4e paramètre. Le nombre de paramètres des fonctions d'entrée est fixe — un 4e paramètre rend le point d'entrée indétectable.

Modules natifs​

Tous les modules préfixés $ sont injectés à l'activation du runtime. Ils sont implémentés nativement, retournent de façon synchrone (sauf mention contraire) et traitent les entrées chaîne comme de l'UTF-8.

$codec — Encodage & décodage​

Base64 / Hex / percent-encoding d'URL pour la conversion de protocole et le transfert de données.

MéthodeRetour
$codec.base64Encode(str)Chaîne Base64.
$codec.base64Decode(str)Chaîne décodée ; une entrée invalide renvoie "" (sans lever d'exception).
$codec.hexEncode(str)Chaîne hex minuscule.
$codec.hexDecode(str)Chaîne décodée ; les caractères invalides sont ignorés.
$codec.urlEncode(str)Chaîne encodée en pourcentage.
$codec.urlDecode(str)Chaîne décodée ; les séquences invalides sont renvoyées telles quelles.
$codec.base64Encode("Hello, World!"); // "SGVsbG8sIFdvcmxkIQ=="
$codec.base64Decode("SGVsbG8sIFdvcmxkIQ=="); // "Hello, World!"
$codec.hexEncode("ABC"); // "414243"
$codec.hexDecode("414243"); // "ABC"
$codec.urlEncode("hello world&foo=bar"); // "hello%20world%26foo%3Dbar"

$hash — Hachage​

Calcul d'empreintes pour les contrôles d'intégrité, l'adressage de contenu et l'anonymisation. Retourne de l'hex minuscule.

MéthodeLongueur de sortie
$hash.md5(str)32 caractères hex
$hash.sha1(str)40 caractères hex
$hash.sha256(str)64 caractères hex
$hash.sha384(str)96 caractères hex
$hash.sha512(str)128 caractères hex
$hash.md5("hello"); // "5d41402abc4b2a76b9719d911017c592"
$hash.sha256("hello"); // "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

// integrity check
const checksum = $hash.sha256(JSON.stringify({user: "admin"}));

$hmac — Code d'authentification de message​

Hachage avec clé pour la signature d'API et la détection de falsification. (data, key) sont tous deux encodés en UTF-8 ; retourne de l'hex minuscule.

MéthodeAlgorithme
$hmac.md5(data, key)HMAC-MD5
$hmac.sha1(data, key)HMAC-SHA1
$hmac.sha256(data, key)HMAC-SHA256
$hmac.sha384(data, key)HMAC-SHA384
$hmac.sha512(data, key)HMAC-SHA512
const signature = $hmac.sha256("important data", "my-secret-key");
const isValid = (signature === $hmac.sha256("important data", "my-secret-key")); // true

$crypto — Chiffrement symétrique​

Chiffrement authentifié AES-GCM (recommandé) et DES (compatibilité historique).

MéthodeRetour
$crypto.encryptAES(plaintext, password, options?)Ciphertext Base64 ; les échecs renvoient une chaîne "Error: <reason>".
$crypto.decryptAES(ciphertext, password, options?)Plaintext ; un ciphertext invalide renvoie "Error: Invalid ciphertext".
$crypto.encryptDES(plaintext, key)DES-ECB + PKCS7, clé tronquée à 8 octets → Base64.
$crypto.decryptDES(ciphertext, key)Plaintext ; une entrée non-Base64 renvoie "".

options : { keySize: 128 \| 192 \| 256 } (défaut 256). Le format du ciphertext AES est base64(nonce[12] + ciphertext + tag[16]) — à apparier avec decryptAES ; pour interopérer avec d'autres langages, vous devez déballer vous-même ce format.

const encrypted = $crypto.encryptAES("sensitive data", "my-password");
$crypto.decryptAES(encrypted, "my-password"); // "sensitive data"

// 128-bit key
const e128 = $crypto.encryptAES("data", "pass", { keySize: 128 });

// errors are returned as strings, not thrown — check the prefix
const out = $crypto.decryptAES("not-base64!!", "p");
if (out.startsWith("Error:")) { /* handle error */ }

$jwt — JSON Web Token​

Création, analyse et vérification de signature JWT (famille HMAC) pour les scripts de flux d'authentification.

MéthodeRetour
$jwt.sign(payload, secret, algorithm?)Chaîne JWT ; défaut HS256.
$jwt.decode(token)Objet {header, payload} (la signature n'est pas vérifiée) ; renvoie null pour un token malformé.
$jwt.verify(token, secret, algorithm?)boolean — résultat de la vérification de signature.

algorithm : "HS256" | "HS384" | "HS512".

// sign
const payload = JSON.stringify({ sub: "user123", exp: Math.floor(Date.now() / 1000) + 3600 });
const token = $jwt.sign(payload, "my-secret", "HS256");

// decode — returns an object directly, no JSON.parse needed
const decoded = $jwt.decode(token);
decoded.header.alg; // "HS256"
decoded.payload.sub; // "user123"

// verify
$jwt.verify(token, "my-secret", "HS256"); // true
$jwt.verify(token, "wrong-secret", "HS256"); // false

// expiry check
const exp = $jwt.decode(token).payload.exp;
const expired = exp * 1000 < Date.now();

$format — Formatage de données​

Pretty-print et minification JSON/XML pour la journalisation et le débogage. Les clés JSON sont triées alphabétiquement dans la sortie.

MéthodeRetour
$format.json(str, indent?)JSON pretty-printé ; indent borné à 1–8 (défaut 2) ; une entrée invalide renvoie "Error: Invalid JSON".
$format.minify(str)JSON minifié (clés triées, sans espaces) ; une entrée invalide renvoie "Error: Invalid JSON".
$format.xml(str)XML simplement indenté.
$format.json('{"b":1,"a":2}');
// {
// "a": 2,
// "b": 1
// }
$format.json('{"a":2}', 4); // 4-space indent
$format.minify('{ "a": 2 }'); // '{"a":2}'
$format.xml('<root><child>t</child></root>');
// <root>
// <child>t</child>
// </root>

$fs — Système de fichiers​

Lecture/écriture de fichiers légère dans les scripts (config, cache, export). Les chemins prennent en charge l'expansion ~ ; write crée automatiquement les répertoires parents manquants.

MéthodeRetour
$fs.read(path)Contenu UTF-8 ; un échec renvoie "Error: Cannot read file at <path>".
$fs.readBinary(path)Octets en Base64 ; un échec renvoie "".
$fs.write(path, content)boolean — succès.
$fs.exists(path)boolean.
$fs.delete(path)boolean ; les fichiers absents renvoient false.
$fs.list(path)string[] des entrées du répertoire ; un échec renvoie [].
$fs.info(path)Chaîne JSON {size, modified, isDirectory, path} ; les chemins absents renvoient undefined.
const file = $env.tmpDir() + "/hodor-test.txt";
$fs.write(file, "Hello from Hodor!");
$fs.read(file); // "Hello from Hodor!"
$fs.exists(file); // true
$fs.list($env.tmpDir()); // ["hodor-test.txt", ...]

const info = JSON.parse($fs.info(file));
info.size; // byte count
info.isDirectory; // false

$fs.delete(file); // true
remarque

Les formes d'échec diffèrent selon la méthode : read renvoie une chaîne "Error: ...", readBinary renvoie "", list renvoie [] et info renvoie undefined — gérez chaque cas en conséquence.

$env — Variables d'environnement​

Variables d'environnement du processus et chemins système. Note : $env est l'environnement du processus (partagé entre les exécutions, vit avec le processus). Pour persister des variables côté utilisateur, utilisez plutôt sdk.setEnvVar ou SharedPreferences.

MéthodeRetour
$env.get(key)Valeur ; les clés absentes renvoient "".
$env.set(key, value)boolean — résultat du setenv.
$env.all()Chaîne JSON de toutes les variables d'environnement.
$env.cwd()Répertoire de travail courant.
$env.tmpDir()Répertoire temporaire.
$env.homeDir()Répertoire home de l'utilisateur.
$env.set("APP_VERSION", "1.0.0");
$env.get("APP_VERSION"); // "1.0.0"
const all = JSON.parse($env.all());

$uuid — UUID​

Générer et valider des UUID (ID de requête, clés d'idempotence).

MéthodeRetour
$uuid.v4()UUID v4 standard (majuscule, avec tirets), ex. "550e8400-E29B-41D4-A716-446655440000".
$uuid.compact()Forme sans tirets, en minuscules.
$uuid.validate(str)Indique si la chaîne est un UUID valide.
const id = $uuid.v4();
$uuid.compact(); // "550e8400e29b41d4a716446655440000"
$uuid.validate($uuid.v4()); // true
$uuid.validate("not-uuid"); // false
remarque

validate n'accepte que le format avec tirets — validate($uuid.compact()) renvoie false. Réinsérez les tirets avant de valider une chaîne compacte.

$log — Journalisation structurée​

Lignes de log horodatées et nivelées, routées via le système console du moteur (collectées dans la vue de logs du script).

MéthodeRetour
$log.log(level, message, tag?)Ligne de log formatée (aussi imprimée).
$log.debug / info / warn / error(message)Méthodes de niveau pratiques, sortie uniquement.

Format de ligne de log : [yyyy-MM-dd'T'HH:mm:ss.SSSZ] [LEVEL] [tag] message (le segment [tag] est omis quand aucun tag n'est fourni).

$log.info("Server started on port 8080");
// [2025-07-24T01:11:45.548+0800] [INFO] Server started on port 8080
$log.log("info", "Request processed", "API");
// [2025-07-24T01:11:45.548+0800] [INFO] [API] Request processed

API Web​

fetch​

Envoie de vraies requêtes HTTP depuis les scripts — le canal principal des workflows façon Postman.

fetch(url: string, options?: object) → Promise<response>

options :

ChampTypeDéfautDescription
methodstring"GET"Insensible à la casse ; les valeurs inconnues retombent sur GET.
timeoutIntervalnumber30Secondes.
headers[[k, v]] ou [{k: v}][]Les deux formes sont acceptées.
textBodystring—Texte du body de requête.
encodingstring—"hex" signifie que textBody est une chaîne hex.

La valeur résolue est un objet simple : statusCode (number), headers (tableau d'objets à clé unique, clés dupliquées préservées) et textBody() — une fonction qui renvoie {text, encoding} avec détection automatique du jeu de caractères (les corps indécodables retombent sur {text: <hex>, encoding: "hex"}). La valeur de rejet est une chaîne de message d'erreur.

// GET
const rsp = await fetch("https://httpbin.org/get");
if (rsp.statusCode === 200) {
const body = rsp.textBody(); // {text: "...", encoding: "utf-8"}
const json = JSON.parse(body.text);
}

// POST JSON
const rsp2 = await fetch("https://httpbin.org/post", {
method: "POST",
headers: [["Content-Type", "application/json"]],
textBody: JSON.stringify({a: 1}),
timeoutInterval: 10,
});

HTTPClient​

La classe HTTPClient envoie des requêtes HTTP depuis n'importe quel script (implémentée au-dessus de fetch). Toutes les méthodes sont async et renvoient un objet de réponse avec statusCode, headers et textBody().

MéthodeDescription
HTTPClient.get(url, params?)Envoie une requête GET.
HTTPClient.post(url, params?)Envoie une requête POST.
HTTPClient.put(url, params?)Envoie une requête PUT.
HTTPClient.update(url, params?)Envoie une requête UPDATE.
HTTPClient.delete(url, params?)Envoie une requête DELETE.
HTTPClient.request(url, method, params?)Envoie une requête avec une méthode personnalisée.

params est un objet optionnel avec :

  • headers : objet de headers de requête, ex. {"key1": "value1"}
  • body : corps de la requête — une chaîne, un objet JSON (sérialisé automatiquement) ou un URLSearchParams
  • timeoutInterval : délai d'attente en secondes (défaut 60)
try {
var params = {
"headers": {"key1": "value1"},
"body": {"a": "a1", "b": "b1"},
};
const response = await HTTPClient.post("https://dummyjson.com/products/1", params);
console.log(response.textBody().text);
} catch(error) {
console.log(error);
}

Minuteries (Timers)​

setTimeout / setInterval / clearTimeout / clearInterval fonctionnent comme dans les navigateurs. Les callbacks sont dispatchés sur une file série du moteur, donc les timers se déclenchent de façon fiable quel que soit le thread hôte.

FonctionRetour
setTimeout(callback, ms)Id de timer (string), se déclenche une fois.
setInterval(callback, ms)Id de timer, se déclenche en boucle.
clearTimeout(id) / clearInterval(id)Annule (idempotent, les ids inconnus sont ignorés).
await new Promise(resolve => setTimeout(resolve, 500)); // wait 0.5s
const timer = setInterval(() => console.log("tick"), 1000);
setTimeout(() => clearInterval(timer), 3500);

Fonctions globales​

NomSignatureDescription
btoa(str)(string) → stringEncodage Base64 — sémantique symétrique UTF-8 (les chaînes non Latin-1 sont autorisées, contrairement aux navigateurs).
atob(str)(string) → stringDécodage Base64 ; une entrée invalide renvoie "".
performance.now()() → numberMillisecondes depuis l'epoch (pas le chargement de page).
sleep(ms)(number) → PromiseSe résout après ms ; utilisez await sleep(1000).
require(id)(string) → anyCharge une bibliothèque de scripts selon la sémantique CommonJS (module.exports) ; la clé est @libs/<key>, résolue comme identifiant de bibliothèque → nom de bibliothèque (unique) → bibliothèques intégrées ; lève une exception si introuvable.
TextEncodernew TextEncoder().encode(str)Encode en UTF-8 dans un Uint8Array (encoding vaut toujours "utf-8").
crypto.getRandomValues(n)(Array) → number[]Remplit avec n valeurs UInt32 aléatoires.
crypto.randomUUID()() → stringUUID aléatoire (majuscule, avec tirets).
btoa("Hello"); // "SGVsbG8="
atob("SGVsbG8="); // "Hello"
btoa("中文"); // works — UTF-8 bytes are encoded
performance.now(); // 1760000000000.123
await sleep(100);
const { encode } = require("@libs/base64"); // built-in lib
const { sign } = require("@libs/sign-lib"); // your script library
new TextEncoder().encode("hi"); // Uint8Array [104, 105]

Les bibliothèques sont gérées dans le gestionnaire de modules de scripts. La clé de require est toujours @libs/<key> : vos bibliothèques de scripts se résolvent d'abord par identifiant (stable lors des renommages), puis par nom (correspondance unique), puis par les bibliothèques intégrées @libs/base64 / @libs/hex. Les bibliothèques exportent via module.exports, peuvent require d'autres bibliothèques, et une clé manquante lève une exception (un échec en pré-envoi interrompt la requête, un échec en post-réponse conserve la réponse d'origine). Voir scripts Quick Request, Require de bibliothèques de scripts pour le guide complet.

console​

console.log / info / warn / error imprime des valeurs dans la vue de logs du script. Les arguments multiples sont sérialisés, donc vous pouvez logger directement objets et tableaux :

console.log("headers", {Accept: "application/json"}, [1, 2, 3]);

$log offre une sortie structurée et nivelée (voir $log) — les deux canaux sont visibles dans la vue de logs de script de Hodor.

Classes HTTP​

Request​

La classe Request est la requête HTTP empaquetée passée à onRequest / onSessionCompleted.

MembreTypeDescription
schemestring (get / set)Le scheme de la requête, ex. https.
hoststring (get / set)Le host de la requête.
portnumber (get / set)Le port de la requête.
pathstring (get / set)Le path de la requête.
methodstring (get / set)La méthode HTTP, ex. GET.
queriesURLSearchParams (get)Les query params de la requête.
headersHeaders (get)Les headers de la requête.
bodyBody (get) / string | Map | Array | URLSearchParams (set)Le body de la requête.
remarque

Les headers doivent être modifiés avec .set() / .append() — l'affectation par index (ex. headers["X-Key"] = v) est ignorée.

Vous pouvez aussi construire une requête vous-même :

const request = new Request({
scheme: 'https',
host: 'example.com',
port: 8080,
path: '/api',
method: 'GET',
queries: 'param1=value1&param2=value2',
headers: [
['Content-Type', 'application/json'],
['Authorization', 'Bearer token']
],
textBody: '{"key": "value"}'
});
console.log(request.encode());

Response​

La classe Response représente la réponse HTTP passée à onResponse / onSessionCompleted.

MembreTypeDescription
statusCodenumber (get / set)Le code de statut de la réponse.
statusPhrasestring (get / set)La phrase de statut de la réponse, ex. OK.
headersHeaders (get)Les headers de la réponse.
bodyBody (get) / string | Map | Array | URLSearchParams (set)Le body de la réponse.
const response = new Response({
statusCode: 404,
statusPhrase: 'Not Found',
headers: {
'Content-Type': 'application/json',
'Cache-Control': 'no-cache'
},
textBody: '{"error": "Resource not found"}'
});
console.log(response.encode());

Body​

La classe Body représente le corps d'une requête ou d'une réponse HTTP. Affecter une nouvelle valeur à request.body / response.body remplace tout le corps.

MéthodeRetourDescription
parseText()string | nullAnalyse le corps comme texte.
parseJSON()object | nullAnalyse le corps comme JSON.
parseURLSearchParams()URLSearchParams | nullAnalyse le corps comme paramètres URL-encodés.
const bodyInstance = new Body('{"user": "alice"}');
const json = bodyInstance.parseJSON();
if (json) {
console.log('User:' + json.user);
} else {
console.error('Failed to parse JSON');
}

Headers​

La classe Headers représente des headers HTTP.

MéthodeRetourDescription
append(name, value)voidAjoute une valeur au header spécifié.
set(name, value)voidDéfinit (remplace) la valeur du header spécifié.
get(name)string | nullObtient la valeur du header spécifié.
has(name)booleanVérifie si le header spécifié existe.
delete(name)voidSupprime le header spécifié.
forEach(callback, thisArg?)voidAppelle une fonction pour chaque header.
entries() / keys() / values()IteratorItère sur les entrées / clés / valeurs.
encode()ArrayEncode les headers dans un format sérialisable.
const headers = new Headers();
headers.append('Content-Type', 'application/json');
headers.set('Content-Length', '1024');
console.log(headers.get('Content-Type')); // 'application/json'
console.log(headers.has('Authorization')); // false
headers.forEach((value, name) => {
console.log(name + ' ' + value);
});

URLSearchParams​

La classe URLSearchParams représente les paramètres de query d'URL (ou de body urlencoded).

MéthodeRetourDescription
append(name, value)voidAjoute une valeur au paramètre spécifié.
set(name, value)voidDéfinit (remplace) la valeur du paramètre spécifié.
get(name)string | nullObtient la valeur du paramètre spécifié.
has(name)booleanVérifie si le paramètre spécifié existe.
delete(name)voidSupprime le paramètre spécifié.
forEach(callback, thisArg?)voidAppelle une fonction pour chaque paramètre.
entries() / keys() / values()IteratorItère sur les entrées / clés / valeurs.
sort()voidTrie les paramètres.
toString()stringSérialise en chaîne urlencodée.
const params = new URLSearchParams({ key1: 'value1', key2: 'value2' });
console.log(params.get('key1')); // 'value1'
console.log(params.get('key3')); // null
params.forEach((value, key) => console.log(key + ' ' + value));

SharedPreferences​

La classe SharedPreferences fournit un stockage clé-valeur local persistant qui survit aux exécutions de scripts et aux redémarrages de l'app (adossé aux user defaults du système).

MéthodeRetourDescription
SharedPreferences.write(key, value)voidÉcrit une valeur (string / number / boolean / object / array). Écrire null supprime la clé.
SharedPreferences.read(key)anyLit la valeur associée à la clé, ou null si elle n'existe pas.
SharedPreferences.write("test_key", "test_value");
const value = SharedPreferences.read("test_key");
console.log(value);

SharedPreferences.write("cfg", {a: 1}); // objects are stored directly
SharedPreferences.write("cfg", null); // deletes "cfg"

sdk — Scripts Quick Request​

sdk (alias pm) est injecté uniquement dans les scripts pre/post Quick Request. Il fait le pont avec le stockage de variables de l'app (environnements, variables globales et d'exécution) et collecte les assertions, avec une forme d'API façon Postman.

MembreDescription
sdk.env.get(key)Lit une variable d'environnement définie dans l'app.
sdk.env.set(key, value)Définit une variable d'environnement (identique à sdk.setEnvVar).
sdk.setEnvVar(key, value)Écrit une variable d'env — collectée et persistée vers l'app.
sdk.setVar(key, value)Écrit une variable d'exécution (locale).
sdk.setGlobalVar(key, value)Écrit une variable globale.
sdk.getVar(key)Lit une variable d'exécution.
sdk.test(name, fn)Exécute un bloc d'assertion nommé ; les échecs sont collectés et signalés dans l'app.
sdk.expect(value)Primitives d'assertion : toBe, toEqual, toBeTruthy.
sdk.jsonPath(object, path)Recherche par chemin pointé, ex. "$.data.list[0].id".
sdk.utils.uuid()Identique à crypto.randomUUID().
sdk.utils.base64Encode(s) / base64Decode(s)Identique à btoa / atob.
sdk.utils.md5(s)Identique à $hash.md5.
// Quick Request pre-request script: sign the request
async function onRequest(context, url, request) {
// read variables defined in the app's environment
const secret = sdk.env.get("secret") || "test-key";
sdk.expect(secret).toBeTruthy();

const ts = String(Date.now());
const bodyText = request.body && request.body.text ? request.body.text : '';
const sig = $hmac.sha256(ts + bodyText, secret);

// headers must be set via .set / .append
request.headers.set("X-Signature", sig);
request.headers.set("X-Timestamp", ts);

// persist variables back to the app
sdk.setEnvVar("lastTs", ts);
sdk.test("signature is 64 hex", () => {
sdk.expect(sig.length).toBe(64);
});

console.log("signed request for", url);
return request;
}
remarque

Les résultats d'assertion sont signalés pour les scripts de pré-requête. Dans les scripts de post-réponse, les assertions s'exécutent mais les résultats ne sont pas collectés.

Contextes​

RewriteContext​

L'objet de contexte passé aux scripts de réécriture (onRequest / onResponse).

MembreTypeDescription
isEnableOnRequestboolean (get)Indique si le point d'entrée onRequest est activé.
isEnableOnResponseboolean (get)Indique si le point d'entrée onResponse est activé.
parametersobject (get / set)Un dictionnaire de paramètres partagé entre onRequest et onResponse.
scriptNamestring (get)Le nom du script.

CompletedContext​

L'objet de contexte passé aux scripts HTTP Completed.

MembreTypeDescription
sessionobject (get)L'objet de session associé au script completed.
scriptNamestring (get)Le nom du script completed.

ScheduleContext​

L'objet de contexte passé aux scripts planifiés.

MembreTypeDescription
parametersobject (get / set)Paramètres passés à la prochaine boucle d'exécution quand définis.
cronstring (get)L'expression cron de la planification.
repeatedCountnumber (get)Combien de fois le script a été répété.
scriptNamestring (get)Le nom du script planifié.

Notes de comportement​

  • Les exceptions non interceptées font échouer le script. Les erreurs (y compris AbortError de abort()) remontent à Hodor et l'exécution est signalée comme échouée — les réécritures partielles faites avant l'erreur sont abandonnées, protégez donc les blocs risqués avec try / catch.
  • Chien de garde de délai d'attente. Chaque exécution de script a un budget de temps ; un script qui ne se termine jamais (ex. boucle infinie ou await suspendu) est interrompu de force et signalé comme timeout.
  • Erreurs comme valeurs de retour. Certaines API ne lèvent jamais d'exception : $codec.base64Decode renvoie "", $crypto renvoie des chaînes "Error: ...", $fs.read renvoie des chaînes "Error: ..." et $fs.info renvoie undefined. Vérifiez ces valeurs de retour au lieu de compter sur try / catch.
  • console.log vs $log. Les deux sont visibles dans la vue de logs de script ; $log ajoute horodatages et niveaux.
  • Persistance du runtime de script. Les variables écrites avec sdk.setVar et les fichiers écrits avec $fs restent disponibles pour les exécutions suivantes du même script ; SharedPreferences persiste à travers les redémarrages de l'app.