Syntax and Interface

Basic Methods

$script.name: Script name
$script.type: Script type, such as request, response and tile
$script.startTime: The time when the script starts running
$environment["stash-build"]: Stash Build number
$environment["stash-version"]: Stash version number
$environment.language: Stash running language
$environment.system: Stash running system (iOS / macOS)
$argument: Running parameters. Only present when argument is configured.
$done(value): End the script run and release resources
$notification.post(title, subtitle, body): Send a system notification
console.log(value): Output log, script log will be output to a separate file. Objects are serialized as JSON automatically.
setTimeout(callback, delay): Delay execution of callback function

When a script throws an uncaught exception, the run ends immediately and the error is written to the script log.

Timers

iOS/tvOS3.6+macOS4.3+

Besides setTimeout, scripts can use setInterval, clearTimeout, clearInterval, and queueMicrotask. Timers that have not fired are cancelled when the script run ends.

`$done(value)`

⚠️

For all scripts, you must call the $done(value) method to release resources at the end.

Only the first call to $done takes effect. When a script runs in the script editor, the value passed to $done is shown in the editor for debugging.

Persistent Storage

$persistentStore.write(value, key): Write to persistent storage. value must be a string; returns true on success.
$persistentStore.read(key): Read from persistent storage; returns null when the entry does not exist.

When key is omitted, the script name is used as the key, so the same script shares one entry across HTTP rewriting, scheduled tasks, and tiles. To share data between different scripts, pass the same explicit key.

HTTP Client

$httpClient.get(url<String>, callback<Function>)
$httpClient.get(request<Object>, callback<Function>)

Similarly, there are:

$httpClient.post()
$httpClient.put()
$httpClient.delete()
$httpClient.head()
$httpClient.options()
$httpClient.patch()

The request object supports the following fields:

Field	Type	Description
`url`	string	Required. The request URL
`headers`	object	Request headers. Set `X-Stash-Selected-Proxy` to choose the proxy for the request; encode the value with `encodeURIComponent`
`body`	string / object / Uint8Array / ArrayBuffer	Request body. Objects are serialized as a JSON string
`timeout`	number	Timeout in seconds, 5 by default
`insecure`	boolean	Skip HTTPS certificate verification when `true`, `false` by default
`binary-mode`	boolean	Deliver the response `data` as a `Uint8Array` when `true`, `false` by default
`auto-cookie`	boolean	Handle cookies automatically, `true` by default
`auto-redirect`	boolean	Follow 3xx redirects automatically, `true` by default

The callback signature is callback(error, response, data): on failure error is an error message string; on success response carries status (also available as statusCode) and headers, and data is the response body. Header names in the headers object are case-insensitive.

For example:


$httpClient.get('http://httpbin.org/get', (error, response, data) => {
  if (error) {
    console.log(error)
  } else {
    console.log(data)
  }
})
 
const yourProxyName = 'a fancy name with 😄'
 
$httpClient.post(
  {
    url: 'http://httpbin.org/post',
    headers: {
      'X-Header-Key': 'headerValue',
      'X-Stash-Selected-Proxy': encodeURIComponent(yourProxyName),
    },
    body: '{}', // can be object or string
    timeout: 5,
    insecure: false,
    'binary-mode': true,
    'auto-cookie': true,
    'auto-redirect': true,
  },
  (error, response, data) => {
    if (error) {
      console.log(error)
    } else {
      console.log(data)
    }
  }
)