Saltar al contenido principal

Referencia de la API de scripts

Hodor ejecuta tus scripts en un motor JavaScript integrado. Según el tipo de script, Hodor llama a una de las funciones de entrada de abajo en el momento adecuado — tú solo implementas la lógica que necesites. Si no modificas nada, elimina la función de entrada no usada para evitar llamadas innecesarias.

Objetos y clases globales disponibles:

CategoríaNombres
Funciones de entradaonRequest, onResponse, onSessionCompleted, onSchedule, abort()
Módulos nativos $$codec, $hash, $hmac, $crypto, $jwt, $format, $fs, $env, $uuid, $log
APIs estándar webfetch, HTTPClient, setTimeout / setInterval, btoa / atob / sleep / require / TextEncoder / crypto, console
Clases HTTPRequest, Response, Body, Headers, URLSearchParams
AlmacenamientoSharedPreferences, variables sdk
ContextosRewriteContext, CompletedContext, ScheduleContext
consejo

Usa console.log(...) en cualquier punto del script para inspeccionar valores — la salida se muestra en la vista de log del script.

Funciones de entrada​

Los scripts se detectan buscando declaraciones async function — el número de parámetros de cada función de entrada es fijo (onRequest/onResponse toman 3, onSessionCompleted toma 4, onSchedule toma 1). Las asignaciones de arrow-function (let onRequest = async (...) => {}) no se detectan. Los nombres de los parámetros son libres.

onRequest(context, url, request)​

Pensada para scripts de reescritura y scripts de envío previo de Quick Request. Se llama antes de enviar la solicitud HTTP al servidor. Devuelve el request (posiblemente modificado).

ParámetroTipoDescripción
contextRewriteContextEl objeto de contexto.
urlstringLa URL de la solicitud HTTP.
requestRequestEl objeto de solicitud 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)​

Pensada para scripts de reescritura y scripts de post-respuesta de Quick Request. Se llama antes de entregar la respuesta HTTP al cliente. Devuelve la response (posiblemente modificada).

ParámetroTipoDescripción
contextRewriteContextEl objeto de contexto.
urlstringLa URL de la respuesta HTTP.
responseResponseEl objeto de respuesta 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)​

Pensada para scripts de completed HTTP. Se llama de forma asíncrona cuando vuelve la respuesta HTTP, sin afectar a la transmisión de datos entre la app y el servidor. Útil para recoger y reenviar datos.

ParámetroTipoDescripción
contextCompletedContextEl objeto de contexto.
urlstringLa URL de la solicitud HTTP.
requestRequestEl objeto de solicitud HTTP.
responseResponseEl objeto de respuesta 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)​

Pensada para scripts programados. Se llama en el momento de disparo programado (se admiten expresiones cron de 5 o 6 partes). Usa abort() para detener el bucle de programación.

ParámetroTipoDescripción
contextScheduleContextEl objeto de contexto.
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()​

Dentro de los scripts de canal (onRequest / onResponse / onSchedule), llama a abort() para detener el script y abortar de inmediato la ejecución en curso — lanza un AbortError que Hodor te notifica.

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

No declares onRequest(context, url, request, aborter) con un 4.º parámetro. El número de parámetros de las funciones de entrada es fijo — un 4.º parámetro hace el punto de entrada indetectable.

Módulos nativos​

Todos los módulos con prefijo $ se inyectan al activarse el runtime. Están implementados de forma nativa, devuelven de forma síncrona (salvo indicación) y tratan las entradas de cadena como UTF-8.

$codec — Codificar y decodificar​

Base64 / Hex / codificación percentual de URL para conversión de protocolos y transferencia de datos.

MétodoDevuelve
$codec.base64Encode(str)Cadena Base64.
$codec.base64Decode(str)Cadena decodificada; la entrada inválida devuelve "" (no lanza).
$codec.hexEncode(str)Cadena hex en minúsculas.
$codec.hexDecode(str)Cadena decodificada; los caracteres inválidos se omiten.
$codec.urlEncode(str)Cadena con codificación percentual.
$codec.urlDecode(str)Cadena decodificada; las secuencias inválidas se devuelven tal cual.
$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 — Resúmenes hash​

Cálculo de resúmenes para comprobaciones de integridad, direccionamiento por contenido y anonimización. Devuelve hex en minúsculas.

MétodoLongitud de salida
$hash.md5(str)32 caracteres hex
$hash.sha1(str)40 caracteres hex
$hash.sha256(str)64 caracteres hex
$hash.sha384(str)96 caracteres hex
$hash.sha512(str)128 caracteres hex
$hash.md5("hello"); // "5d41402abc4b2a76b9719d911017c592"
$hash.sha256("hello"); // "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

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

$hmac — Message Authentication Code​

Hash con clave para firmas de API y detección de manipulaciones. Tanto (data, key) se codifican en UTF-8; devuelve hex en minúsculas.

MétodoAlgoritmo
$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 — Cifrado simétrico​

Cifrado autenticado AES-GCM (recomendado) y DES (compatibilidad heredada).

MétodoDevuelve
$crypto.encryptAES(plaintext, password, options?)Ciphertext en Base64; los fallos devuelven una cadena "Error: <reason>".
$crypto.decryptAES(ciphertext, password, options?)Plaintext; un ciphertext inválido devuelve "Error: Invalid ciphertext".
$crypto.encryptDES(plaintext, key)DES-ECB + PKCS7, clave truncada a 8 bytes → Base64.
$crypto.decryptDES(ciphertext, key)Plaintext; una entrada no Base64 devuelve "".

options: { keySize: 128 \| 192 \| 256 } (por defecto 256). El formato del ciphertext AES es base64(nonce[12] + ciphertext + tag[16]) — úsalo en pareja con decryptAES; al interoperar con otros lenguajes debes desempaquetar este formato por tu cuenta.

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​

Creación, análisis y verificación de firma de JWT (familia HMAC) para scripts de flujos de autenticación.

MétodoDevuelve
$jwt.sign(payload, secret, algorithm?)Cadena JWT; por defecto HS256.
$jwt.decode(token)Objeto {header, payload} (la firma no se verifica); devuelve null con tokens malformados.
$jwt.verify(token, secret, algorithm?)boolean — resultado de la verificación de firma.

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 — Formateo de datos​

Pretty-printing y minificado de JSON/XML para logging y depuración. Las claves JSON se ordenan alfabéticamente en la salida.

MétodoDevuelve
$format.json(str, indent?)JSON con formato bonito; la indentación se limita a 1–8 (por defecto 2); la entrada inválida devuelve "Error: Invalid JSON".
$format.minify(str)JSON minificado (claves ordenadas, sin espacios en blanco); la entrada inválida devuelve "Error: Invalid JSON".
$format.xml(str)XML con indentación simple.
$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 — Sistema de archivos​

Lectura/escritura ligera de archivos dentro de los scripts (configuración, caché, exportación). Las rutas admiten la expansión de ~; write crea automáticamente los directorios padre que falten.

MétodoDevuelve
$fs.read(path)Contenido UTF-8; un fallo devuelve "Error: Cannot read file at <path>".
$fs.readBinary(path)Bytes como Base64; un fallo devuelve "".
$fs.write(path, content)boolean — éxito.
$fs.exists(path)boolean.
$fs.delete(path)boolean; los archivos inexistentes devuelven false.
$fs.list(path)string[] de entradas del directorio; un fallo devuelve [].
$fs.info(path)Cadena JSON {size, modified, isDirectory, path}; las rutas inexistentes devuelven 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
nota

Las formas de fallo difieren según el método: read devuelve una cadena "Error: ...", readBinary devuelve "", list devuelve [] y info devuelve undefined — trátalos en consecuencia.

$env — Variables de entorno​

Variables de entorno del proceso y rutas del sistema. Nota: $env es el entorno del proceso (compartido entre ejecuciones, vive con el proceso). Para persistir variables de usuario usa en su lugar sdk.setEnvVar o SharedPreferences.

MétodoDevuelve
$env.get(key)Valor; las claves ausentes devuelven "".
$env.set(key, value)boolean — resultado de setenv.
$env.all()Cadena JSON de todas las variables de entorno.
$env.cwd()Directorio de trabajo actual.
$env.tmpDir()Directorio temporal.
$env.homeDir()Directorio personal del usuario.
$env.set("APP_VERSION", "1.0.0");
$env.get("APP_VERSION"); // "1.0.0"
const all = JSON.parse($env.all());

$uuid — UUID​

Genera y valida UUIDs (IDs de solicitud, claves de idempotencia).

MétodoDevuelve
$uuid.v4()UUID v4 estándar (mayúsculas, con guiones), p. ej. "550e8400-E29B-41D4-A716-446655440000".
$uuid.compact()Forma sin guiones, en minúsculas.
$uuid.validate(str)Si la cadena es un UUID válido.
const id = $uuid.v4();
$uuid.compact(); // "550e8400e29b41d4a716446655440000"
$uuid.validate($uuid.v4()); // true
$uuid.validate("not-uuid"); // false
nota

validate solo acepta el formato con guiones — validate($uuid.compact()) devuelve false. Vuelve a insertar los guiones antes de validar una cadena compacta.

$log — Logging estructurado​

Líneas de log con marca de tiempo y nivel, enrutadas por el sistema de consola del motor (recogidas en la vista de log del script).

MétodoDevuelve
$log.log(level, message, tag?)Línea de log formateada (también se imprime).
$log.debug / info / warn / error(message)Métodos de conveniencia por nivel, solo salida.

Formato de línea de log: [yyyy-MM-dd'T'HH:mm:ss.SSSZ] [LEVEL] [tag] message (el segmento [tag] se omite si no se indica tag).

$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

APIs web​

fetch​

Envía solicitudes HTTP reales desde los scripts — el canal principal para flujos de trabajo al estilo Postman.

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

options:

CampoTipoPor defectoDescripción
methodstring"GET"Insensible a mayúsculas; los valores desconocidos caen a GET.
timeoutIntervalnumber30Segundos.
headers[[k, v]] o [{k: v}][]Se aceptan ambas formas.
textBodystring—Texto del cuerpo de la solicitud.
encodingstring—"hex" significa que textBody es una cadena hex.

El valor resuelto es un objeto sencillo: statusCode (number), headers (array de objetos de una sola clave, con las claves duplicadas conservadas) y textBody() — una función que devuelve {text, encoding} con detección automática del juego de caracteres (los cuerpos indecodificables caen a {text: <hex>, encoding: "hex"}). El valor de rechazo es una cadena de mensaje de error.

// 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 clase HTTPClient envía solicitudes HTTP desde cualquier script (implementada sobre fetch). Todos los métodos son async y devuelven un objeto de respuesta con statusCode, headers y textBody().

MétodoDescripción
HTTPClient.get(url, params?)Envía una solicitud GET.
HTTPClient.post(url, params?)Envía una solicitud POST.
HTTPClient.put(url, params?)Envía una solicitud PUT.
HTTPClient.update(url, params?)Envía una solicitud UPDATE.
HTTPClient.delete(url, params?)Envía una solicitud DELETE.
HTTPClient.request(url, method, params?)Envía una solicitud con un método personalizado.

params es un objeto opcional con:

  • headers: objeto de cabeceras de la solicitud, p. ej. {"key1": "value1"}
  • body: cuerpo de la solicitud — una cadena, un objeto JSON (serializado automáticamente) o URLSearchParams
  • timeoutInterval: tiempo de espera en segundos (por defecto 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);
}

Temporizadores​

setTimeout / setInterval / clearTimeout / clearInterval funcionan como en los navegadores. Los callbacks se despachan en una cola en serie del motor, por lo que los temporizadores se disparan de forma fiable independientemente del hilo anfitrión.

FunciónDevuelve
setTimeout(callback, ms)Id de temporizador (string), se dispara una vez.
setInterval(callback, ms)Id de temporizador, se dispara repetidamente.
clearTimeout(id) / clearInterval(id)Cancela (idempotente, los ids desconocidos se ignoran).
await new Promise(resolve => setTimeout(resolve, 500)); // wait 0.5s
const timer = setInterval(() => console.log("tick"), 1000);
setTimeout(() => clearInterval(timer), 3500);

Funciones globales​

NombreFirmaDescripción
btoa(str)(string) → stringCodificación Base64 — semántica simétrica UTF-8 (se permiten cadenas no Latin1, a diferencia de los navegadores).
atob(str)(string) → stringDecodificación Base64; la entrada inválida devuelve "".
performance.now()() → numberMilisegundos desde la época (no desde la carga de la página).
sleep(ms)(number) → PromiseSe resuelve tras ms; usa await sleep(1000).
require(id)(string) → anyCarga una biblioteca de scripts con semántica CommonJS (module.exports); la clave es @libs/<key>, resuelta como identificador de la biblioteca de scripts → nombre de la biblioteca (único) → bibliotecas integradas; lanza error si no se encuentra.
TextEncodernew TextEncoder().encode(str)Codifica UTF-8 en un Uint8Array (encoding siempre es "utf-8").
crypto.getRandomValues(n)(Array) → number[]Rellena con n valores UInt32 aleatorios.
crypto.randomUUID()() → stringUUID aleatorio (mayúsculas, con guiones).
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]

Las bibliotecas se gestionan en el gestor de módulos de scripts. La clave de require siempre es @libs/<key>: tus bibliotecas de scripts se resuelven primero por identificador (estable ante renombrados), luego por nombre (coincidencia única) y después las bibliotecas integradas @libs/base64 / @libs/hex. Las bibliotecas exportan vía module.exports, pueden requerir otras bibliotecas y una clave faltante lanza error (los fallos de envío previo abortan la solicitud; los de post-respuesta conservan la respuesta original). Consulta Scripts de Quick Request, Require de bibliotecas de scripts para la guía completa.

console​

console.log / info / warn / error imprime valores en la vista de log del script. Los argumentos múltiples se serializan, así que puedes loguear objetos y arrays directamente:

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

$log ofrece salida estructurada y por niveles (ver $log) — ambos canales son visibles en la vista de log de scripts de Hodor.

Clases HTTP​

Request​

La clase Request es la solicitud HTTP empaquetada que se pasa a onRequest / onSessionCompleted.

MiembroTipoDescripción
schemestring (get / set)El scheme de la solicitud, p. ej. https.
hoststring (get / set)El host de la solicitud.
portnumber (get / set)El puerto de la solicitud.
pathstring (get / set)La ruta de la solicitud.
methodstring (get / set)El método HTTP, p. ej. GET.
queriesURLSearchParams (get)Los query params de la solicitud.
headersHeaders (get)Las cabeceras de la solicitud.
bodyBody (get) / string | Map | Array | URLSearchParams (set)El cuerpo de la solicitud.
nota

Las cabeceras deben modificarse con .set() / .append() — la asignación por índice (p. ej. headers["X-Key"] = v) se ignora.

También puedes construir una solicitud tú mismo:

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 clase Response representa la respuesta HTTP que se pasa a onResponse / onSessionCompleted.

MiembroTipoDescripción
statusCodenumber (get / set)El código de estado de la respuesta.
statusPhrasestring (get / set)La frase de estado de la respuesta, p. ej. OK.
headersHeaders (get)Las cabeceras de la respuesta.
bodyBody (get) / string | Map | Array | URLSearchParams (set)El cuerpo de la respuesta.
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 clase Body representa el cuerpo de una solicitud o respuesta HTTP. Asignar un nuevo valor a request.body / response.body reemplaza todo el cuerpo.

MétodoDevuelveDescripción
parseText()string | nullAnaliza el cuerpo como texto.
parseJSON()object | nullAnaliza el cuerpo como JSON.
parseURLSearchParams()URLSearchParams | nullAnaliza el cuerpo como parámetros urlencoded.
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 clase Headers representa las cabeceras HTTP.

MétodoDevuelveDescripción
append(name, value)voidAñade un valor a la cabecera indicada.
set(name, value)voidEstablece (reemplaza) el valor de la cabecera indicada.
get(name)string | nullObtiene el valor de la cabecera indicada.
has(name)booleanComprueba si existe la cabecera indicada.
delete(name)voidElimina la cabecera indicada.
forEach(callback, thisArg?)voidLlama a una función por cada cabecera.
entries() / keys() / values()IteratorItera sobre entradas / claves / valores.
encode()ArrayCodifica las cabeceras a un formato serializable.
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 clase URLSearchParams representa los parámetros de query de URL (o de cuerpo urlencoded).

MétodoDevuelveDescripción
append(name, value)voidAñade un valor al parámetro indicado.
set(name, value)voidEstablece (reemplaza) el valor del parámetro indicado.
get(name)string | nullObtiene el valor del parámetro indicado.
has(name)booleanComprueba si existe el parámetro indicado.
delete(name)voidElimina el parámetro indicado.
forEach(callback, thisArg?)voidLlama a una función por cada parámetro.
entries() / keys() / values()IteratorItera sobre entradas / claves / valores.
sort()voidOrdena los parámetros.
toString()stringSerializa a una cadena urlencoded.
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 clase SharedPreferences ofrece un almacenamiento local persistente clave-valor que sobrevive a las ejecuciones de scripts y a los reinicios de la app (respaldado por los user defaults del sistema).

MétodoDevuelveDescripción
SharedPreferences.write(key, value)voidEscribe un valor (string / number / boolean / objeto / array). Escribir null elimina la clave.
SharedPreferences.read(key)anyLee el valor asociado a la clave, o null si no existe.
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 de Quick Request​

sdk (alias pm) se inyecta solo en los scripts de envío previo / post-respuesta de Quick Request. Hace de puente con el almacenamiento de variables de la app (entornos, variables globales y de ejecución) y recoge aserciones, con una forma de API similar a Postman.

MiembroDescripción
sdk.env.get(key)Lee una variable de entorno definida en la app.
sdk.env.set(key, value)Establece una variable de entorno (igual que sdk.setEnvVar).
sdk.setEnvVar(key, value)Escribe una variable de entorno — se recoge y persiste de vuelta en la app.
sdk.setVar(key, value)Escribe una variable de ejecución (local).
sdk.setGlobalVar(key, value)Escribe una variable global.
sdk.getVar(key)Lee una variable de ejecución.
sdk.test(name, fn)Ejecuta un bloque de aserciones con nombre; los fallos se recogen y se notifican en la app.
sdk.expect(value)Primitivas de aserción: toBe, toEqual, toBeTruthy.
sdk.jsonPath(object, path)Búsqueda por ruta con puntos, p. ej. "$.data.list[0].id".
sdk.utils.uuid()Igual que crypto.randomUUID().
sdk.utils.base64Encode(s) / base64Decode(s)Igual que btoa / atob.
sdk.utils.md5(s)Igual que $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;
}
nota

Los resultados de las aserciones se notifican para los scripts de envío previo. En los scripts de post-respuesta las aserciones se ejecutan, pero los resultados no se recogen.

Contextos​

RewriteContext​

El objeto de contexto que se pasa a los scripts de reescritura (onRequest / onResponse).

MiembroTipoDescripción
isEnableOnRequestboolean (get)Si la entrada onRequest está habilitada.
isEnableOnResponseboolean (get)Si la entrada onResponse está habilitada.
parametersobject (get / set)Un diccionario de parámetros compartido entre onRequest y onResponse.
scriptNamestring (get)El nombre del script.

CompletedContext​

El objeto de contexto que se pasa a los scripts de completed HTTP.

MiembroTipoDescripción
sessionobject (get)El objeto de sesión asociado al script de completed.
scriptNamestring (get)El nombre del script de completed.

ScheduleContext​

El objeto de contexto que se pasa a los scripts programados.

MiembroTipoDescripción
parametersobject (get / set)Parámetros que se pasan al siguiente bucle de ejecución cuando se establecen.
cronstring (get)La expresión cron de la programación.
repeatedCountnumber (get)Cuántas veces se ha repetido el script.
scriptNamestring (get)El nombre del script programado.

Notas de comportamiento​

  • Las excepciones no capturadas hacen fallar el script. Los errores (incluido el AbortError de abort()) se propagan a Hodor y la ejecución se notifica como fallida — las reescrituras parciales hechas antes del error se descartan, así que protege los bloques arriesgados con try / catch.
  • Vigilancia de tiempo de espera. Cada ejecución de script tiene un presupuesto de tiempo; un script que nunca termina (p. ej. un bucle infinito o un await colgado) se interrumpe a la fuerza y se notifica como timeout.
  • Errores como valores de retorno. Algunas APIs nunca lanzan: $codec.base64Decode devuelve "", $crypto devuelve cadenas "Error: ...", $fs.read devuelve cadenas "Error: ..." y $fs.info devuelve undefined. Comprueba estos valores de retorno en lugar de confiar en try / catch.
  • console.log vs $log. Ambos son visibles en la vista de log del script; $log añade marcas de tiempo y niveles.
  • Persistencia del runtime de scripts. Las variables escritas con sdk.setVar y los archivos escritos con $fs siguen disponibles para ejecuciones posteriores del mismo script; SharedPreferences persiste entre reinicios de la app.