API Docs

hs.http

Module

HTTP client module for making network requests from JavaScript.

All request methods return Promises that resolve with a result object containing status (number), body (string), and headers (object). On network failure, status is -1 and body is an empty string.

Quick start

hs.http.get("https://api.example.com/data").then(r => {
    if (r.status === 200) {
        console.log("Got: " + r.body)
    }
})

Types

This module provides the following types:

Properties

This module has no properties.

Methods

hs.http.get(url, headers) -> Promise<any>

Perform an HTTP GET request.
Declaration
hs.http.get(url, headers) -> Promise<any>
Parameters
Name Type Description
url string The URL to request.
headers [String: String] Optional dictionary of request headers.
Returns
Promise<any>
{Promise<{status: number, body: string, headers: object}>} Resolves with the HTTP response.
Example
hs.http.get("https://httpbin.org/get").then(r => console.log(r.status))
Hammerspoon 2/Modules/hs.http/HSHTTPModule.swift:33

hs.http.post(url, body, headers) -> Promise<any>

Perform an HTTP POST request.
Declaration
hs.http.post(url, body, headers) -> Promise<any>
Parameters
Name Type Description
url string The URL to request.
body string Optional request body string.
headers [String: String] Optional dictionary of request headers.
Returns
Promise<any>
{Promise<{status: number, body: string, headers: object}>} Resolves with the HTTP response.
Example
hs.http.post("https://httpbin.org/post", '{"key":"val"}', {"Content-Type": "application/json"}).then(r => console.log(r.status))
Hammerspoon 2/Modules/hs.http/HSHTTPModule.swift:44

hs.http.put(url, body, headers) -> Promise<any>

Perform an HTTP PUT request.
Declaration
hs.http.put(url, body, headers) -> Promise<any>
Parameters
Name Type Description
url string The URL to request.
body string Optional request body string.
headers [String: String] Optional dictionary of request headers.
Returns
Promise<any>
{Promise<{status: number, body: string, headers: object}>} Resolves with the HTTP response.
Example
hs.http.put("https://httpbin.org/put", "updated data", null).then(r => console.log(r.status))
Hammerspoon 2/Modules/hs.http/HSHTTPModule.swift:55

hs.http.doRequest(url, method, body, headers) -> Promise<any>

Perform an HTTP request with any method (GET, POST, PUT, DELETE, PATCH, etc.). Use this for methods not covered by the convenience helpers, such as DELETE or PATCH.
Declaration
hs.http.doRequest(url, method, body, headers) -> Promise<any>
Parameters
Name Type Description
url string The URL to request.
method string The HTTP method string (e.g. "DELETE", "PATCH", "HEAD").
body string Optional request body string.
headers [String: String] Optional dictionary of request headers.
Returns
Promise<any>
{Promise<{status: number, body: string, headers: object}>} Resolves with the HTTP response.
Example
hs.http.doRequest("https://httpbin.org/delete", "DELETE", null, null).then(r => console.log(r.status))
Hammerspoon 2/Modules/hs.http/HSHTTPModule.swift:70

hs.http.encodeForQuery(string) -> string

URL-encode a string for use as a query parameter value. Encodes characters that are illegal in a URL query string (including `?`, `=`, `+`, `&`, `#`) using percent-encoding.
Declaration
hs.http.encodeForQuery(string) -> string
Parameters
Name Type Description
string string The string to encode.
Returns
string
The percent-encoded string.
Example
console.log(hs.http.encodeForQuery("hello world & more=stuff"))
// "hello%20world%20%26%20more%3Dstuff"
Hammerspoon 2/Modules/hs.http/HSHTTPModule.swift:84

hs.http.urlParts(url) -> [String: Any]

Parse a URL into its component parts. Returns an object containing only the fields present in the URL. The `queryItems` field is an array of `{name, value}` objects from the query string.
Declaration
hs.http.urlParts(url) -> [String: Any]
Parameters
Name Type Description
url string The URL string to parse.
Returns
[String: Any]
An object with any of the fields: `scheme`, `host`, `port`, `user`, `password`, `path`, `query`, `fragment`, `queryItems`. Returns `null` if the URL is unparseable.
Example
const parts = hs.http.urlParts("https://user:pass@example.com:8080/path?key=val#frag")
console.log(parts.host)  // "example.com"
console.log(parts.port)  // 8080
Hammerspoon 2/Modules/hs.http/HSHTTPModule.swift:99

hs.http.convertHtmlEntities(string) -> string

Convert HTML entities in a string to their UTF-8 character equivalents. Handles named entities (e.g. `&amp;`, `&lt;`, `&copy;`), decimal numeric references (`&#38;`), and hexadecimal numeric references (`&#x26;`).
Declaration
hs.http.convertHtmlEntities(string) -> string
Parameters
Name Type Description
string string The string containing HTML entities.
Returns
string
The string with HTML entities replaced by their UTF-8 characters.
Example
console.log(hs.http.convertHtmlEntities("&lt;div&gt;Hello &amp; World&lt;/div&gt;"))
// "<div>Hello & World</div>"
Hammerspoon 2/Modules/hs.http/HSHTTPModule.swift:113

hs.http.openWebSocket(url) -> HSWebSocket

Open a WebSocket connection to the given URL. The connection begins immediately. Use the returned object's chainable setter methods to register event callbacks. The connection is automatically closed when `hs.reload()` is called or the engine shuts down.
Declaration
hs.http.openWebSocket(url) -> HSWebSocket
Parameters
Name Type Description
url string The WebSocket URL (`ws://` or `wss://`).
Returns
HSWebSocket
An `HSWebSocket` object, or `null` if the URL is invalid.
Example
const ws = hs.http.openWebSocket("ws://localhost:8080/ws")
    .setOpenCallback(() => ws.send("Hello!"))
    .setMessageCallback(msg => console.log("Got: " + msg))
    .setCloseCallback((code, reason) => console.log("Closed: " + code))
Hammerspoon 2/Modules/hs.http/HSHTTPModule.swift:130