Referência da API de scripts
O Hodor executa seus scripts em um motor JavaScript integrado. Dependendo do tipo de script, o Hodor chama uma das funções de entrada abaixo no momento certo — você implementa apenas a lógica de que precisa. Se não for modificar nada, exclua a função de entrada não utilizada para evitar chamadas desnecessárias.
Objetos e classes globais disponíveis:
| Categoria | Nomes |
|---|---|
| Funções de entrada | onRequest, onResponse, onSessionCompleted, onSchedule, abort() |
Módulos nativos $ | $codec, $hash, $hmac, $crypto, $jwt, $format, $fs, $env, $uuid, $log |
| APIs padrão Web | fetch, HTTPClient, setTimeout / setInterval, btoa / atob / sleep / require / TextEncoder / crypto, console |
| Classes HTTP | Request, Response, Body, Headers, URLSearchParams |
| Armazenamento | SharedPreferences, variáveis sdk |
| Contextos | RewriteContext, CompletedContext, ScheduleContext |
Use console.log(...) em qualquer lugar de um script para inspecionar valores — a saída é mostrada na visão de log do script.
Funções de entrada
Os scripts são detectados varrendo declarações async function — a contagem de parâmetros de cada função de entrada é fixa (onRequest/onResponse levam 3, onSessionCompleted leva 4, onSchedule leva 1). Atribuições de arrow function (let onRequest = async (...) => {}) não são detectadas. Os nomes dos parâmetros são livres.
onRequest(context, url, request)
Projetada para Rewrite Script e scripts de pré-requisição do Quick Request. Esta função é chamada antes de a requisição HTTP ser enviada ao servidor. Retorne o request (possivelmente modificado).
| Parâmetro | Tipo | Descrição |
|---|---|---|
context | RewriteContext | O objeto de contexto. |
url | string | A URL da requisição HTTP. |
request | Request | O objeto de requisição 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)
Projetada para Rewrite Script e scripts pós-resposta do Quick Request. Esta função é chamada antes de a resposta HTTP ser enviada ao cliente. Retorne a response (possivelmente modificada).
| Parâmetro | Tipo | Descrição |
|---|---|---|
context | RewriteContext | O objeto de contexto. |
url | string | A URL da resposta HTTP. |
response | Response | O objeto de resposta 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)
Projetada para HTTP Completed Script. Chamada de forma assíncrona depois que a resposta HTTP é retornada, sem afetar a transmissão de dados entre o app e o servidor. Útil para coleta e encaminhamento de dados.
| Parâmetro | Tipo | Descrição |
|---|---|---|
context | CompletedContext | O objeto de contexto. |
url | string | A URL da requisição HTTP. |
request | Request | O objeto de requisição HTTP. |
response | Response | O objeto de resposta 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)
Projetada para Schedule Script. Chamada no horário de disparo agendado (expressões cron de 5 ou 6 partes são suportadas). Use abort() para parar o loop de agendamento.
| Parâmetro | Tipo | Descrição |
|---|---|---|
context | ScheduleContext | O 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 dos scripts de canal (onRequest / onResponse / onSchedule), chame abort() para parar o script e abortar a execução atual imediatamente — ele lança um AbortError que o Hodor reporta de volta a você.
// ✅ correct — abort() is injected into the script scope
async function onRequest(context, url, request) {
if (url.includes("/tracking")) abort();
return request;
}
Não declare onRequest(context, url, request, aborter) com um 4º parâmetro. A contagem de parâmetros das funções de entrada é fixa — um 4º parâmetro torna a entrada indetectável.
Módulos nativos
Todos os módulos prefixados com $ são injetados quando o runtime é ativado. São implementados nativamente, retornam de forma síncrona (salvo indicação em contrário) e tratam entradas de string como UTF-8.
$codec — Codificação e decodificação
Codificação Base64 / Hex / percent-encoding de URL para conversão de protocolo e transferência de dados.
| Método | Retorna |
|---|---|
$codec.base64Encode(str) | String Base64. |
$codec.base64Decode(str) | String decodificada; entrada inválida retorna "" (não lança). |
$codec.hexEncode(str) | String hex minúscula. |
$codec.hexDecode(str) | String decodificada; caracteres inválidos são pulados. |
$codec.urlEncode(str) | String com percent-encoding. |
$codec.urlDecode(str) | String decodificada; sequências inválidas são retornadas como estão. |
$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 — Hash
Cálculo de digest para verificações de integridade, endereçamento de conteúdo e anonimização. Retorna hex minúsculo.
| Método | Comprimento da saída |
|---|---|
$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 — Código de autenticação de mensagem
Hash com chave para assinatura de API e detecção de adulteração. Ambos (data, key) são codificados em UTF-8; retorna hex minúsculo.
| Método | Algoritmo |
|---|---|
$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 — Criptografia simétrica
Criptografia autenticada AES-GCM (recomendada) e DES (compatibilidade legada).
| Método | Retorna |
|---|---|
$crypto.encryptAES(plaintext, password, options?) | Ciphertext Base64; falhas retornam uma string "Error: <reason>". |
$crypto.decryptAES(ciphertext, password, options?) | Plaintext; ciphertext inválido retorna "Error: Invalid ciphertext". |
$crypto.encryptDES(plaintext, key) | DES-ECB + PKCS7, chave truncada para 8 bytes → Base64. |
$crypto.decryptDES(ciphertext, key) | Plaintext; entrada não-Base64 retorna "". |
options: { keySize: 128 \| 192 \| 256 } (padrão 256). O formato do ciphertext AES é base64(nonce[12] + ciphertext + tag[16]) — use-o em par com decryptAES; ao interoperar com outras linguagens você mesmo precisa desempacotar esse formato.
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
Criação, análise e verificação de assinatura de JWT (família HMAC) para scripts de fluxo de autenticação.
| Método | Retorna |
|---|---|
$jwt.sign(payload, secret, algorithm?) | String JWT; padrão HS256. |
$jwt.decode(token) | Objeto {header, payload} (a assinatura não é verificada); retorna null em tokens malformados. |
$jwt.verify(token, secret, algorithm?) | boolean — resultado da verificação da assinatura. |
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 — Formatação de dados
Impressão formatada (pretty-print) e minificação de JSON/XML para logging e depuração. As chaves JSON são ordenadas alfabeticamente na saída.
| Método | Retorna |
|---|---|
$format.json(str, indent?) | JSON formatado; indentação limitada a 1–8 (padrão 2); entrada inválida retorna "Error: Invalid JSON". |
$format.minify(str) | JSON minificado (chaves ordenadas, sem whitespace); entrada inválida retorna "Error: Invalid JSON". |
$format.xml(str) | XML simples com indentação. |
$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 arquivos
Leitura/escrita leve de arquivos dentro dos scripts (config, cache, export). Os caminhos suportam expansão ~; write cria automaticamente os diretórios pai ausentes.
| Método | Retorna |
|---|---|
$fs.read(path) | Conteúdo UTF-8; falha retorna "Error: Cannot read file at <path>". |
$fs.readBinary(path) | Bytes como Base64; falha retorna "". |
$fs.write(path, content) | boolean — sucesso. |
$fs.exists(path) | boolean. |
$fs.delete(path) | boolean; arquivos ausentes retornam false. |
$fs.list(path) | string[] das entradas do diretório; falha retorna []. |
$fs.info(path) | String JSON {size, modified, isDirectory, path}; caminhos ausentes retornam 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
O formato de falha difere por método: read retorna uma string "Error: ...", readBinary retorna "", list retorna [] e info retorna undefined — trate cada um adequadamente.
$env — Variáveis de ambiente
Variáveis de ambiente do processo e caminhos do sistema. Nota: $env é o ambiente do processo (compartilhado entre execuções, vive com o processo). Para persistir variáveis voltadas ao usuário, use sdk.setEnvVar ou SharedPreferences.
| Método | Retorna |
|---|---|
$env.get(key) | Valor; chaves ausentes retornam "". |
$env.set(key, value) | boolean — resultado do setenv. |
$env.all() | String JSON de todas as variáveis de ambiente. |
$env.cwd() | Diretório de trabalho atual. |
$env.tmpDir() | Diretório temporário. |
$env.homeDir() | Diretório home do usuário. |
$env.set("APP_VERSION", "1.0.0");
$env.get("APP_VERSION"); // "1.0.0"
const all = JSON.parse($env.all());
$uuid — UUID
Gera e valida UUIDs (IDs de requisição, chaves de idempotência).
| Método | Retorna |
|---|---|
$uuid.v4() | UUID v4 padrão (maiúsculo, com hífens), ex.: "550e8400-E29B-41D4-A716-446655440000". |
$uuid.compact() | Forma sem hífens, minúscula. |
$uuid.validate(str) | Se a string é um UUID válido. |
const id = $uuid.v4();
$uuid.compact(); // "550e8400e29b41d4a716446655440000"
$uuid.validate($uuid.v4()); // true
$uuid.validate("not-uuid"); // false
validate só aceita o formato com hífens — validate($uuid.compact()) retorna false. Reinsera os hífens antes de validar uma string compacta.
$log — Log estruturado
Linhas de log com timestamp e nível roteadas pelo sistema de console do motor (coletadas na visão de log do script).
| Método | Retorna |
|---|---|
$log.log(level, message, tag?) | Linha de log formatada (também impressa). |
$log.debug / info / warn / error(message) | Métodos de conveniência por nível, apenas saída. |
Formato da linha de log: [yyyy-MM-dd'T'HH:mm:ss.SSSZ] [LEVEL] [tag] message (o segmento [tag] é omitido quando nenhuma tag é dada).
$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
Envia requisições HTTP reais a partir dos scripts — o canal principal para fluxos de trabalho estilo Postman.
fetch(url: string, options?: object) → Promise<response>
options:
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
method | string | "GET" | Não diferencia maiúsculas; valores desconhecidos caem para GET. |
timeoutInterval | number | 30 | Segundos. |
headers | [[k, v]] ou [{k: v}] | [] | Ambas as formas são aceitas. |
textBody | string | — | Texto do corpo da requisição. |
encoding | string | — | "hex" significa que textBody é uma string hex. |
O valor resolvido é um objeto simples: statusCode (número), headers (array de objetos de chave única, chaves duplicadas preservadas) e textBody() — uma função que retorna {text, encoding} com detecção automática de charset (corpos não decodificáveis caem para {text: <hex>, encoding: "hex"}). O valor rejeitado é uma string de mensagem de erro.
// 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
A classe HTTPClient envia requisições HTTP de qualquer script (implementada sobre o fetch). Todos os métodos são async e retornam um objeto de resposta com statusCode, headers e textBody().
| Método | Descrição |
|---|---|
HTTPClient.get(url, params?) | Envia uma requisição GET. |
HTTPClient.post(url, params?) | Envia uma requisição POST. |
HTTPClient.put(url, params?) | Envia uma requisição PUT. |
HTTPClient.update(url, params?) | Envia uma requisição UPDATE. |
HTTPClient.delete(url, params?) | Envia uma requisição DELETE. |
HTTPClient.request(url, method, params?) | Envia uma requisição com um método personalizado. |
params é um objeto opcional com:
headers: objeto de headers da requisição, ex.:{"key1": "value1"}body: corpo da requisição — uma string, objeto JSON (serializado automaticamente) ou URLSearchParamstimeoutInterval: timeout em segundos (padrão 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);
}
Timers
setTimeout / setInterval / clearTimeout / clearInterval funcionam como nos browsers. Os callbacks são despachados em uma fila serial do motor, então os timers disparam de forma confiável independentemente da thread hospedeira.
| Função | Retorna |
|---|---|
setTimeout(callback, ms) | ID do timer (string), dispara uma vez. |
setInterval(callback, ms) | ID do timer, dispara repetidamente. |
clearTimeout(id) / clearInterval(id) | Cancela (idempotente, IDs desconhecidos são ignorados). |
await new Promise(resolve => setTimeout(resolve, 500)); // wait 0.5s
const timer = setInterval(() => console.log("tick"), 1000);
setTimeout(() => clearInterval(timer), 3500);
Funções globais
| Nome | Assinatura | Descrição |
|---|---|---|
btoa(str) | (string) → string | Codificação Base64 — semântica simétrica UTF-8 (strings não-Latin1 são permitidas, diferente dos browsers). |
atob(str) | (string) → string | Decodificação Base64; entrada inválida retorna "". |
performance.now() | () → number | Milissegundos desde a época (não o carregamento da página). |
sleep(ms) | (number) → Promise | Resolve após ms; use await sleep(1000). |
require(id) | (string) → any | Carrega uma biblioteca de scripts com semântica CommonJS (module.exports); a chave é @libs/<key>, resolvida como identificador da biblioteca → nome da biblioteca (único) → bibliotecas integradas; lança erro quando não encontrada. |
TextEncoder | new TextEncoder().encode(str) | Codifica em UTF-8 para um Uint8Array (encoding é sempre "utf-8"). |
crypto.getRandomValues(n) | (Array) → number[] | Preenche com n valores UInt32 aleatórios. |
crypto.randomUUID() | () → string | UUID aleatório (maiúsculo, com hífens). |
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]
As bibliotecas são gerenciadas no gerenciador de módulos de script. A chave de require é sempre @libs/<key>: suas bibliotecas de scripts resolvem primeiro por identificador (estável entre renomeações), depois por nome (correspondência única) e depois pelas bibliotecas integradas @libs/base64 / @libs/hex. Bibliotecas exportam via module.exports, podem requerer outras bibliotecas, e uma chave ausente lança erro (falhas de pré-envio abortam a requisição, falhas de pós-resposta mantêm a resposta original). Veja scripting do Quick Request, Require de bibliotecas de scripts para o guia completo.
console
console.log / info / warn / error imprime valores na visão de log do script. Múltiplos argumentos são serializados, então você pode logar objetos e arrays diretamente:
console.log("headers", {Accept: "application/json"}, [1, 2, 3]);
$log oferece saída estruturada e nivelada (veja $log) — ambos os canais são visíveis na visão de log de scripts do Hodor.
Classes HTTP
Request
A classe Request é a requisição HTTP empacotada passada para onRequest / onSessionCompleted.
| Membro | Tipo | Descrição |
|---|---|---|
scheme | string (get / set) | O scheme da requisição, ex.: https. |
host | string (get / set) | O host da requisição. |
port | number (get / set) | A porta da requisição. |
path | string (get / set) | O caminho da requisição. |
method | string (get / set) | O método HTTP, ex.: GET. |
queries | URLSearchParams (get) | Os query params da requisição. |
headers | Headers (get) | Os headers da requisição. |
body | Body (get) / string | Map | Array | URLSearchParams (set) | O corpo da requisição. |
Headers devem ser modificados com .set() / .append() — atribuição por índice (ex.: headers["X-Key"] = v) é ignorada.
Você também pode construir uma requisição você mesmo:
const request = new Request({
scheme: 'https',
host: 'example.com',
port: 8080,
path: '/api',
method: 'GET',
queries: 'param1=value1¶m2=value2',
headers: [
['Content-Type', 'application/json'],
['Authorization', 'Bearer token']
],
textBody: '{"key": "value"}'
});
console.log(request.encode());
Response
A classe Response representa a resposta HTTP passada para onResponse / onSessionCompleted.
| Membro | Tipo | Descrição |
|---|---|---|
statusCode | number (get / set) | O código de status da resposta. |
statusPhrase | string (get / set) | A frase de status da resposta, ex.: OK. |
headers | Headers (get) | Os headers da resposta. |
body | Body (get) / string | Map | Array | URLSearchParams (set) | O corpo da resposta. |
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
A classe Body representa o corpo de uma requisição ou resposta HTTP. Atribuir um novo valor a request.body / response.body substitui o corpo inteiro.
| Método | Retorna | Descrição |
|---|---|---|
parseText() | string | null | Analisa o corpo como texto. |
parseJSON() | object | null | Analisa o corpo como JSON. |
parseURLSearchParams() | URLSearchParams | null | Analisa o corpo como parâmetros URL-encoded. |
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
A classe Headers representa headers HTTP.
| Método | Retorna | Descrição |
|---|---|---|
append(name, value) | void | Anexa um valor ao header especificado. |
set(name, value) | void | Define (substitui) o valor do header especificado. |
get(name) | string | null | Obtém o valor do header especificado. |
has(name) | boolean | Verifica se o header especificado existe. |
delete(name) | void | Exclui o header especificado. |
forEach(callback, thisArg?) | void | Chama uma função para cada header. |
entries() / keys() / values() | Iterator | Itera sobre entradas / chaves / valores. |
encode() | Array | Codifica os headers em um formato serializável. |
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
A classe URLSearchParams representa parâmetros de query de URL (ou corpo urlencoded).
| Método | Retorna | Descrição |
|---|---|---|
append(name, value) | void | Anexa um valor ao parâmetro especificado. |
set(name, value) | void | Define (substitui) o valor do parâmetro especificado. |
get(name) | string | null | Obtém o valor do parâmetro especificado. |
has(name) | boolean | Verifica se o parâmetro especificado existe. |
delete(name) | void | Exclui o parâmetro especificado. |
forEach(callback, thisArg?) | void | Chama uma função para cada parâmetro. |
entries() / keys() / values() | Iterator | Itera sobre entradas / chaves / valores. |
sort() | void | Ordena os parâmetros. |
toString() | string | Serializa para uma string 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
A classe SharedPreferences fornece armazenamento persistente local de chave-valor que sobrevive a execuções de script e reinícios do app (respaldado pelos user defaults do sistema).
| Método | Retorna | Descrição |
|---|---|---|
SharedPreferences.write(key, value) | void | Escreve um valor (string / número / boolean / objeto / array). Escrever null exclui a chave. |
SharedPreferences.read(key) | any | Lê o valor associado à chave, ou null se não existir. |
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 do Quick Request
sdk (alias pm) é injetado apenas nos scripts pré/pós do Quick Request. Ele faz a ponte com o armazenamento de variáveis do app (ambientes, variáveis globais e de runtime) e coleta asserções, com um formato de API estilo Postman.
| Membro | Descrição |
|---|---|
sdk.env.get(key) | Lê uma variável de ambiente definida no app. |
sdk.env.set(key, value) | Define uma variável de ambiente (igual a sdk.setEnvVar). |
sdk.setEnvVar(key, value) | Escreve uma variável de ambiente — coletada e persistida de volta no app. |
sdk.setVar(key, value) | Escreve uma variável de runtime (local). |
sdk.setGlobalVar(key, value) | Escreve uma variável global. |
sdk.getVar(key) | Lê uma variável de runtime. |
sdk.test(name, fn) | Roda um bloco de asserção nomeado; falhas são coletadas e reportadas no app. |
sdk.expect(value) | Primitivas de asserção: toBe, toEqual, toBeTruthy. |
sdk.jsonPath(object, path) | Busca por dot-path, ex.: "$.data.list[0].id". |
sdk.utils.uuid() | Igual a crypto.randomUUID(). |
sdk.utils.base64Encode(s) / base64Decode(s) | Igual a btoa / atob. |
sdk.utils.md5(s) | Igual a $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;
}
Os resultados de asserções são reportados para scripts de pré-requisição. Em scripts pós-resposta, as asserções rodam, mas os resultados não são coletados.
Contextos
RewriteContext
O objeto de contexto passado para os scripts de reescrita (onRequest / onResponse).
| Membro | Tipo | Descrição |
|---|---|---|
isEnableOnRequest | boolean (get) | Se a entrada onRequest está habilitada. |
isEnableOnResponse | boolean (get) | Se a entrada onResponse está habilitada. |
parameters | object (get / set) | Um dicionário de parâmetros compartilhado entre onRequest e onResponse. |
scriptName | string (get) | O nome do script. |
CompletedContext
O objeto de contexto passado para os scripts HTTP Completed.
| Membro | Tipo | Descrição |
|---|---|---|
session | object (get) | O objeto de sessão associado ao script completed. |
scriptName | string (get) | O nome do script completed. |
ScheduleContext
O objeto de contexto passado para os scripts agendados.
| Membro | Tipo | Descrição |
|---|---|---|
parameters | object (get / set) | Parâmetros passados para o próximo runloop quando definidos. |
cron | string (get) | A expressão cron do agendamento. |
repeatedCount | number (get) | Quantas vezes o script foi repetido. |
scriptName | string (get) | O nome do script agendado. |
Notas de comportamento
- Exceções não capturadas falham o script. Erros (incluindo
AbortErrordeabort()) propagam para o Hodor e a execução é reportada como falha — reescritas parciais feitas antes do erro são descartadas, então proteja blocos arriscados comtry / catch. - Watchdog de timeout. Cada execução de script tem um orçamento de tempo; um script que nunca termina (ex.: loop infinito ou
awaittravado) é interrompido à força e reportado como timeout. - Erros como valores de retorno. Algumas APIs nunca lançam:
$codec.base64Decoderetorna"",$cryptoretorna strings"Error: ...",$fs.readretorna strings"Error: ..."e$fs.inforetornaundefined. Verifique esses valores de retorno em vez de confiar emtry / catch. console.logvs.$log. Ambos são visíveis na visão de log do script; o$logadiciona timestamps e níveis.- Persistência do runtime de script. Variáveis escritas com
sdk.setVare arquivos escritos com$fspermanecem disponíveis para execuções seguintes do mesmo script;SharedPreferencespersiste entre reinícios do app.