Przejdź do głównej zawartości

Dokumentacja API skryptów

Hodor uruchamia Twoje skrypty we wbudowanym silniku JavaScript. W zależności od typu skryptu Hodor wywołuje w odpowiednim momencie jedną z poniższych funkcji wejściowych — implementujesz tylko potrzebną logikę. Jeśli czegoś nie modyfikujesz, usuń nieużywaną funkcję wejściową, aby uniknąć zbędnych wywołań.

Dostępne globalne obiekty i klasy:

KategoriaNazwy
Funkcje wejścioweonRequest, onResponse, onSessionCompleted, onSchedule, abort()
Natywne moduły $$codec, $hash, $hmac, $crypto, $jwt, $format, $fs, $env, $uuid, $log
Standardowe API webowefetch, HTTPClient, setTimeout / setInterval, btoa / atob / sleep / require / TextEncoder / crypto, console
Klasy HTTPRequest, Response, Body, Headers, URLSearchParams
PrzechowywanieSharedPreferences, zmienne sdk
KontekstyRewriteContext, CompletedContext, ScheduleContext
wskazówka

Użyj console.log(...) w dowolnym miejscu skryptu, aby podejrzeć wartości — wyjście pokazuje się w widoku logów skryptu.

Funkcje wejściowe​

Skrypty są wykrywane przez skanowanie w poszukiwaniu deklaracji async function — liczba parametrów każdej funkcji wejściowej jest stała (onRequest/onResponse przyjmują 3, onSessionCompleted przyjmuje 4, onSchedule przyjmuje 1). Przypisania funkcji strzałkowych (let onRequest = async (...) => {}) nie są wykrywane. Nazwy parametrów są dowolne.

onRequest(context, url, request)​

Przeznaczona dla Rewrite Script i skryptów przed wysłaniem Quick Request. Funkcja wywoływana przed wysłaniem żądania HTTP do serwera. Zwróć (ewentualnie zmodyfikowane) request.

ParametrTypOpis
contextRewriteContextObiekt kontekstu.
urlstringURL żądania HTTP.
requestRequestObiekt żądania 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)​

Przeznaczona dla Rewrite Script i skryptów po odpowiedzi Quick Request. Funkcja wywoływana przed odesłaniem odpowiedzi HTTP do klienta. Zwróć (ewentualnie zmodyfikowaną) response.

ParametrTypOpis
contextRewriteContextObiekt kontekstu.
urlstringURL odpowiedzi HTTP.
responseResponseObiekt odpowiedzi 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)​

Przeznaczona dla HTTP Completed Script. Wywoływana asynchronicznie po zwróceniu odpowiedzi HTTP, bez wpływu na transmisję danych między aplikacją a serwerem. Przydatna do zbierania i przekazywania danych.

ParametrTypOpis
contextCompletedContextObiekt kontekstu.
urlstringURL żądania HTTP.
requestRequestObiekt żądania HTTP.
responseResponseObiekt odpowiedzi 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)​

Przeznaczona dla Schedule Script. Wywoływana w zaplanowanym momencie wyzwalania (obsługiwane są wyrażenia cron 5- lub 6-częściowe). Użyj abort(), aby zatrzymać pętlę harmonogramu.

ParametrTypOpis
contextScheduleContextObiekt kontekstu.
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()​

Wewnątrz skryptów kanału (onRequest / onResponse / onSchedule) wywołaj abort(), aby zatrzymać skrypt i natychmiast przerwać bieżące wykonanie — rzuca AbortError, który Hodor raportuje z powrotem do Ciebie.

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

Nie deklaruj onRequest(context, url, request, aborter) z czwartym parametrem. Liczba parametrów funkcji wejściowych jest stała — czwarty parametr sprawia, że punkt wejścia staje się niewykrywalny.

Moduły natywne​

Wszystkie moduły z prefiksem $ są wstrzykiwane przy aktywacji środowiska wykonawczego. Są zaimplementowane natywnie, zwracają synchronicznie (chyba że zaznaczono) i traktują wejściowe ciągi jako UTF-8.

$codec — Kodowanie i dekodowanie​

Base64 / Hex / kodowanie procentowe URL do konwersji protokołów i transferu danych.

MetodaZwraca
$codec.base64Encode(str)Ciąg Base64.
$codec.base64Decode(str)Zdekodowany ciąg; niepoprawne wejście zwraca "" (nie rzuca wyjątku).
$codec.hexEncode(str)Ciąg hex małymi literami.
$codec.hexDecode(str)Zdekodowany ciąg; niepoprawne znaki są pomijane.
$codec.urlEncode(str)Ciąg zakodowany procentowo.
$codec.urlDecode(str)Zdekodowany ciąg; niepoprawne sekwencje zwracane są w oryginalnej postaci.
$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 — Funkcje skrótu​

Obliczanie skrótów dla kontroli integralności, adresowania treści i anonimizacji. Zwraca hex małymi literami.

MetodaDługość wyjścia
$hash.md5(str)32 znaki hex
$hash.sha1(str)40 znaków hex
$hash.sha256(str)64 znaki hex
$hash.sha384(str)96 znaków hex
$hash.sha512(str)128 znaków hex
$hash.md5("hello"); // "5d41402abc4b2a76b9719d911017c592"
$hash.sha256("hello"); // "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

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

$hmac — Kod uwierzytelniania wiadomości​

Haszowanie z kluczem do podpisywania API i wykrywania manipulacji. Zarówno (data, key) są kodowane UTF-8; zwraca hex małymi literami.

MetodaAlgorytm
$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 — Szyfrowanie symetryczne​

Uwierzytelnione szyfrowanie AES-GCM (zalecane) oraz DES (dla zgodności ze starszymi systemami).

MetodaZwraca
$crypto.encryptAES(plaintext, password, options?)Szyfrogram Base64; niepowodzenia zwracają ciąg "Error: <reason>".
$crypto.decryptAES(ciphertext, password, options?)Tekst jawny; niepoprawny szyfrogram zwraca "Error: Invalid ciphertext".
$crypto.encryptDES(plaintext, key)DES-ECB + PKCS7, klucz skracany do 8 bajtów → Base64.
$crypto.decryptDES(ciphertext, key)Tekst jawny; wejście spoza Base64 zwraca "".

options: { keySize: 128 \| 192 \| 256 } (domyślnie 256). Format szyfrogramu AES to base64(nonce[12] + ciphertext + tag[16]) — używaj go w parze z decryptAES; przy interoperacyjności z innymi językami musisz sam rozpakować ten 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​

Tworzenie, parsowanie i weryfikacja podpisu JWT (rodzina HMAC) dla skryptów przepływów uwierzytelniania.

MetodaZwraca
$jwt.sign(payload, secret, algorithm?)Ciąg JWT; domyślnie HS256.
$jwt.decode(token)Obiekt {header, payload} (podpis nie jest weryfikowany); dla zniekształconych tokenów zwraca null.
$jwt.verify(token, secret, algorithm?)boolean — wynik weryfikacji podpisu.

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 — Formatowanie danych​

Formatowanie JSON/XML (pretty-print) i minifikacja do logowania i debugowania. Klucze JSON w wyjściu są sortowane alfabetycznie.

MetodaZwraca
$format.json(str, indent?)Sformatowany JSON; wcięcie ograniczone do 1–8 (domyślnie 2); niepoprawne wejście zwraca "Error: Invalid JSON".
$format.minify(str)Zminifikowany JSON (posortowane klucze, bez białych znaków); niepoprawne wejście zwraca "Error: Invalid JSON".
$format.xml(str)Prosty XML z wcięciami.
$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 — System plików​

Lekkie odczytywanie/zapisywanie plików wewnątrz skryptów (konfiguracja, cache, eksport). Ścieżki obsługują rozwijanie ~; write automatycznie tworzy brakujące katalogi nadrzędne.

MetodaZwraca
$fs.read(path)Treść UTF-8; niepowodzenie zwraca "Error: Cannot read file at <path>".
$fs.readBinary(path)Bajty jako Base64; niepowodzenie zwraca "".
$fs.write(path, content)boolean — sukces.
$fs.exists(path)boolean.
$fs.delete(path)boolean; brakujące pliki zwracają false.
$fs.list(path)string[] wpisów katalogu; niepowodzenie zwraca [].
$fs.info(path)Ciąg JSON {size, modified, isDirectory, path}; brakujące ścieżki zwracają 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
notatka

Kształty niepowodzeń różnią się zależnie od metody: read zwraca ciąg "Error: ...", readBinary zwraca "", list zwraca [], a info zwraca undefined — obsługuj każde odpowiednio.

$env — Zmienne środowiskowe​

Zmienne środowiskowe procesu i ścieżki systemowe. Uwaga: $env to środowisko procesu (współdzielone między wykonaniami, żyje z procesem). Aby utrwalać zmienne widoczne dla użytkownika, użyj zamiast tego sdk.setEnvVar albo SharedPreferences.

MetodaZwraca
$env.get(key)Wartość; brakujące klucze zwracają "".
$env.set(key, value)boolean — wynik setenv.
$env.all()Ciąg JSON wszystkich zmiennych środowiskowych.
$env.cwd()Bieżący katalog roboczy.
$env.tmpDir()Katalog tymczasowy.
$env.homeDir()Katalog domowy użytkownika.
$env.set("APP_VERSION", "1.0.0");
$env.get("APP_VERSION"); // "1.0.0"
const all = JSON.parse($env.all());

$uuid — UUID​

Generowanie i walidacja UUID (identyfikatory żądań, klucze idempotencji).

MetodaZwraca
$uuid.v4()Standardowy UUID v4 (wielkie litery, z myślnikami), np. "550e8400-E29B-41D4-A716-446655440000".
$uuid.compact()Forma bez myślników, małymi literami.
$uuid.validate(str)Czy ciąg jest poprawnym UUID.
const id = $uuid.v4();
$uuid.compact(); // "550e8400e29b41d4a716446655440000"
$uuid.validate($uuid.v4()); // true
$uuid.validate("not-uuid"); // false
notatka

validate akceptuje wyłącznie format z myślnikami — validate($uuid.compact()) zwraca false. Przed walidacją ciągu compact wstaw ponownie myślniki.

$log — Logowanie strukturalne​

Linie logu ze znacznikiem czasu i poziomem, routowane przez system konsoli silnika (zbierane do widoku logów skryptu).

MetodaZwraca
$log.log(level, message, tag?)Sformatowana linia logu (także wypisywana).
$log.debug / info / warn / error(message)Metody pomocnicze dla poziomów, tylko wyjście.

Format linii logu: [yyyy-MM-dd'T'HH:mm:ss.SSSZ] [LEVEL] [tag] message (segment [tag] jest pomijany, gdy tag nie jest podany).

$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 webowe​

fetch​

Wysyłaj prawdziwe żądania HTTP ze skryptów — główny kanał dla przepływów w stylu Postman.

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

options:

PoleTypDomyślnieOpis
methodstring"GET"Niewrażliwe na wielkość liter; nieznane wartości wracają do GET.
timeoutIntervalnumber30Sekundy.
headers[[k, v]] albo [{k: v}][]Akceptowane są obie formy.
textBodystring—Treść ciała żądania.
encodingstring—"hex" oznacza, że textBody jest ciągiem hex.

Wartością wynikową jest zwykły obiekt: statusCode (number), headers (tablica obiektów o jednym kluczu, z zachowaniem duplikatów) oraz textBody() — funkcja zwracająca {text, encoding} z automatycznym wykrywaniem zestawu znaków (nieodkodowywalne treści wracają jako {text: <hex>, encoding: "hex"}). Wartością odrzucenia jest ciąg z komunikatem błędu.

// 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​

Klasa HTTPClient wysyła żądania HTTP z dowolnego skryptu (zaimplementowana na bazie fetch). Wszystkie metody są async i zwracają obiekt odpowiedzi z statusCode, headers i textBody().

MetodaOpis
HTTPClient.get(url, params?)Wyślij żądanie GET.
HTTPClient.post(url, params?)Wyślij żądanie POST.
HTTPClient.put(url, params?)Wyślij żądanie PUT.
HTTPClient.update(url, params?)Wyślij żądanie UPDATE.
HTTPClient.delete(url, params?)Wyślij żądanie DELETE.
HTTPClient.request(url, method, params?)Wyślij żądanie z niestandardową metodą.

params to opcjonalny obiekt z polami:

  • headers: obiekt nagłówków żądania, np. {"key1": "value1"}
  • body: ciało żądania — ciąg znaków, obiekt JSON (serializowany automatycznie) albo URLSearchParams
  • timeoutInterval: limit czasu w sekundach (domyślnie 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);
}

Timery​

setTimeout / setInterval / clearTimeout / clearInterval działają jak w przeglądarkach. Wywołania zwrotne są dysponowane na szeregowej kolejce silnika, więc timery odpalają niezawodnie niezależnie od wątku gospodarza.

FunkcjaZwraca
setTimeout(callback, ms)Identyfikator timera (string), odpala się raz.
setInterval(callback, ms)Identyfikator timera, odpala się wielokrotnie.
clearTimeout(id) / clearInterval(id)Anuluj (idempotentne, nieznane identyfikatory są ignorowane).
await new Promise(resolve => setTimeout(resolve, 500)); // wait 0.5s
const timer = setInterval(() => console.log("tick"), 1000);
setTimeout(() => clearInterval(timer), 3500);

Funkcje globalne​

NazwaSygnaturaOpis
btoa(str)(string) → stringKodowanie Base64 — symetryczna semantyka UTF-8 (ciągi spoza Latin1 są dozwolone, w przeciwieństwie do przeglądarek).
atob(str)(string) → stringDekodowanie Base64; niepoprawne wejście zwraca "".
performance.now()() → numberMilisekundy od epoki (nie od załadowania strony).
sleep(ms)(number) → PromiseRozwiązuje się po ms; użyj await sleep(1000).
require(id)(string) → anyŁaduje bibliotekę skryptów według semantyki CommonJS (module.exports); klucz to @libs/<key>, rozwiązywany jako identyfikator biblioteki → nazwa biblioteki (unikalna) → biblioteki wbudowane; rzuca wyjątek, gdy nie znaleziono.
TextEncodernew TextEncoder().encode(str)Koduje UTF-8 do Uint8Array (encoding to zawsze "utf-8").
crypto.getRandomValues(n)(Array) → number[]Wypełnia n losowymi wartościami UInt32.
crypto.randomUUID()() → stringLosowy UUID (wielkie litery, z myślnikami).
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]

Bibliotekami zarządza się w menedżerze modułów skryptów. Klucz require to zawsze @libs/<key>: Twoje biblioteki skryptów są rozwiązywane najpierw po identyfikatorze (stabilnym mimo zmian nazwy), potem po nazwie (unikalne dopasowanie), a na końcu wbudowane biblioteki @libs/base64 / @libs/hex. Biblioteki eksportują przez module.exports, mogą require-ować inne biblioteki, a brakujący klucz rzuca wyjątek (niepowodzenie przed wysłaniem przerywa żądanie, niepowodzenie po odpowiedzi zachowuje oryginalną odpowiedź). Pełny przewodnik: Quick Request scripting, Ładowanie bibliotek skryptów przez require().

console​

console.log / info / warn / error wypisuje wartości do widoku logów skryptu. Wiele argumentów jest serializowanych, więc możesz logować obiekty i tablice bezpośrednio:

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

$log oferuje ustrukturyzowane wyjście z poziomami (zobacz $log) — oba kanały są widoczne w widoku logów skryptu Hodor.

Klasy HTTP​

Request​

Klasa Request to spakowane żądanie HTTP przekazywane do onRequest / onSessionCompleted.

SkładowaTypOpis
schemestring (get / set)Schemat żądania, np. https.
hoststring (get / set)Host żądania.
portnumber (get / set)Port żądania.
pathstring (get / set)Ścieżka żądania.
methodstring (get / set)Metoda HTTP, np. GET.
queriesURLSearchParams (get)Parametry zapytania żądania.
headersHeaders (get)Nagłówki żądania.
bodyBody (get) / string | Map | Array | URLSearchParams (set)Ciało żądania.
notatka

Nagłówki muszą być modyfikowane przez .set() / .append() — przypisanie indeksowe (np. headers["X-Key"] = v) jest ignorowane.

Możesz też skonstruować żądanie samodzielnie:

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​

Klasa Response reprezentuje odpowiedź HTTP przekazywaną do onResponse / onSessionCompleted.

SkładowaTypOpis
statusCodenumber (get / set)Kod statusu odpowiedzi.
statusPhrasestring (get / set)Fraza statusu odpowiedzi, np. OK.
headersHeaders (get)Nagłówki odpowiedzi.
bodyBody (get) / string | Map | Array | URLSearchParams (set)Ciało odpowiedzi.
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​

Klasa Body reprezentuje ciało żądania lub odpowiedzi HTTP. Przypisanie nowej wartości do request.body / response.body zastępuje całe ciało.

MetodaZwracaOpis
parseText()string | nullParsuje ciało jako tekst.
parseJSON()object | nullParsuje ciało jako JSON.
parseURLSearchParams()URLSearchParams | nullParsuje ciało jako parametry zakodowane w URL.
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​

Klasa Headers reprezentuje nagłówki HTTP.

MetodaZwracaOpis
append(name, value)voidDokleja wartość do wskazanego nagłówka.
set(name, value)voidUstawia (zastępuje) wartość wskazanego nagłówka.
get(name)string | nullZwraca wartość wskazanego nagłówka.
has(name)booleanSprawdza, czy wskazany nagłówek istnieje.
delete(name)voidUsuwa wskazany nagłówek.
forEach(callback, thisArg?)voidWywołuje funkcję dla każdego nagłówka.
entries() / keys() / values()IteratorIteruje po wpisach / kluczach / wartościach.
encode()ArrayKoduje nagłówki do postaci serializowalnej.
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​

Klasa URLSearchParams reprezentuje parametry zapytania URL (albo ciała urlencoded).

MetodaZwracaOpis
append(name, value)voidDokleja wartość do wskazanego parametru.
set(name, value)voidUstawia (zastępuje) wartość wskazanego parametru.
get(name)string | nullZwraca wartość wskazanego parametru.
has(name)booleanSprawdza, czy wskazany parametr istnieje.
delete(name)voidUsuwa wskazany parametr.
forEach(callback, thisArg?)voidWywołuje funkcję dla każdego parametru.
entries() / keys() / values()IteratorIteruje po wpisach / kluczach / wartościach.
sort()voidSortuje parametry.
toString()stringSerializuje do ciągu 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​

Klasa SharedPreferences zapewnia lokalny trwały magazyn klucz-wartość, który przeżywa wykonania skryptów i restarty aplikacji (oparty na systemowych user defaults).

MetodaZwracaOpis
SharedPreferences.write(key, value)voidZapisuje wartość (string / number / boolean / obiekt / tablica). Zapis null usuwa klucz.
SharedPreferences.read(key)anyZwraca wartość powiązaną z kluczem albo null, jeśli nie istnieje.
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 — skrypty Quick Request​

sdk (alias pm) jest wstrzykiwany wyłącznie w skryptach przed/po Quick Request. Stanowi pomost do magazynu zmiennych aplikacji (środowiska, zmienne globalne i uruchomieniowe) i zbiera asercje, z kształtem API w stylu Postman.

SkładowaOpis
sdk.env.get(key)Odczytuje zmienną środowiskową zdefiniowaną w aplikacji.
sdk.env.set(key, value)Ustawia zmienną środowiskową (to samo co sdk.setEnvVar).
sdk.setEnvVar(key, value)Zapisuje zmienną środowiskową — zbierana i zapisywana z powrotem do aplikacji.
sdk.setVar(key, value)Zapisuje zmienną uruchomieniową (lokalną).
sdk.setGlobalVar(key, value)Zapisuje zmienną globalną.
sdk.getVar(key)Odczytuje zmienną uruchomieniową.
sdk.test(name, fn)Uruchamia nazwany blok asercji; porażki są zbierane i raportowane w aplikacji.
sdk.expect(value)Prymitywy asercji: toBe, toEqual, toBeTruthy.
sdk.jsonPath(object, path)Wyszukiwanie po ścieżce kropkowej, np. "$.data.list[0].id".
sdk.utils.uuid()To samo co crypto.randomUUID().
sdk.utils.base64Encode(s) / base64Decode(s)To samo co btoa / atob.
sdk.utils.md5(s)To samo co $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;
}
notatka

Wyniki asercji są raportowane dla skryptów przed wysłaniem. W skryptach po odpowiedzi asercje się wykonują, ale wyniki nie są zbierane.

Konteksty​

RewriteContext​

Obiekt kontekstu przekazywany do skryptów rewrite (onRequest / onResponse).

SkładowaTypOpis
isEnableOnRequestboolean (get)Czy punkt wejścia onRequest jest włączony.
isEnableOnResponseboolean (get)Czy punkt wejścia onResponse jest włączony.
parametersobject (get / set)Słownik parametrów współdzielony między onRequest i onResponse.
scriptNamestring (get)Nazwa skryptu.

CompletedContext​

Obiekt kontekstu przekazywany do skryptów HTTP completed.

SkładowaTypOpis
sessionobject (get)Obiekt sesji powiązany z ukończonym skryptem.
scriptNamestring (get)Nazwa skryptu completed.

ScheduleContext​

Obiekt kontekstu przekazywany do skryptów harmonogramu.

SkładowaTypOpis
parametersobject (get / set)Parametry przekazywane do następnej pętli, gdy ustawione.
cronstring (get)Wyrażenie cron harmonogramu.
repeatedCountnumber (get)Ile razy skrypt został powtórzony.
scriptNamestring (get)Nazwa skryptu harmonogramu.

Uwagi o zachowaniu​

  • Nieprzechwycone wyjątki zawodzą skrypt. Błędy (w tym AbortError z abort()) propagują do Hodor, a wykonanie jest raportowane jako nieudane — częściowe przepisania wykonane przed błędem są odrzucane, więc zabezpiecz ryzykowne bloki przez try / catch.
  • Strażnik limitu czasu. Każde wykonanie skryptu ma budżet czasowy; skrypt, który nigdy się nie kończy (np. nieskończona pętla albo zawieszony await), zostaje przerwany i raportowany jako timeout.
  • Błędy jako wartości zwrotne. Niektóre API nigdy nie rzucają: $codec.base64Decode zwraca "", $crypto zwraca ciągi "Error: ...", $fs.read zwraca ciągi "Error: ...", a $fs.info zwraca undefined. Sprawdzaj te wartości zwrotne zamiast polegać na try / catch.
  • console.log vs $log. Oba są widoczne w widoku logów skryptu; $log dodaje znaczniki czasu i poziomy.
  • Trwałość środowiska skryptu. Zmienne zapisane przez sdk.setVar i pliki zapisane przez $fs pozostają dostępne dla kolejnych wykonań tego samego skryptu; SharedPreferences przetrwa restarty aplikacji.