Transport for CourtListener: the settings resolver (per-call opts
first, then context variables, then defaults), a typed HttpError,
JSON GETs, and query-string building that drops unset values.
| opts key | Context variable | Default |
|---|---|---|
api-token | courtlistener.api-token | none: token-gated calls fail without it |
base-url | courtlistener.base-url | https://www.courtlistener.com/api/rest/v4 |
Per-call credentials. api-token in opts is masked in call
records and never written to context, so parallel flows and tenants
in one run don't see each other's tokens. Present but blank or null,
it is an error, never a fallback to context. A per-call base-url
needs an api-token in the same opts: the context token is never
sent to a per-call URL.
Context Vars
courtlistener.api-tokencourtlistener.base-url
Values
BASE_URL
BASE_URL: Str "https://www.courtlistener.com/api/rest/v4"
PACKAGE_AGENT
PACKAGE_AGENT: Str "hot-dev-courtlistener-pkg/0.1 (+https://hot.dev)"
SOURCE
SOURCE: Str "courtlistener"
Functions
decode-body
fn (response: ::hot::http/HttpResponse, url: Str): Any
The decoded JSON of a 2xx response, or an Err carrying HttpError when
the body is not JSON (pure). Exposed for testing.
Example
::courtlistener::api/decode-body({status: 200, headers: {}, body: {count: 0}}, "https://www.courtlistener.com/api/rest/v4/dockets/1/") // {count: 0}
is-err(::courtlistener::api/decode-body({status: 200, headers: {}, body: "<html></html>"}, "https://www.courtlistener.com/api/rest/v4/dockets/1/")) // true
get-json
fn (url: Str, headers: Map): Any
GET a JSON resource and return the decoded body, or an Err carrying
HttpError.
Example
token ::hot::ctx/get("courtlistener.api-token")
headers {Authorization: ::courtlistener/auth-header(token)}
out ::courtlistener::api/get-json("https://www.courtlistener.com/api/rest/v4/dockets/4214664/", headers)
out.case_name
get-json-or-null
fn (url: Str, headers: Map): Any
get-json, but a 404 gives null (no such record) instead of an Err.
Example
token ::hot::ctx/get("courtlistener.api-token")
headers {Authorization: ::courtlistener/auth-header(token)}
out ::courtlistener::api/get-json-or-null("https://www.courtlistener.com/api/rest/v4/dockets/1/", headers)
is-null(out)
given
fn (v: Any): Bool
True for a non-null value that is not a blank string.
Example
::courtlistener::api/given("x") // true
::courtlistener::api/given(" ") // false
::courtlistener::api/given(null) // false
http-error
fn (response: ::hot::http/HttpResponse, url: Str): HttpError
Build an HttpError from a non-2xx response. Exposed for testing; every
request uses it.
Example
e ::courtlistener::api/http-error({status: 429, headers: {retry-after: "60"}, body: {detail: "Request was throttled."}}, "https://www.courtlistener.com/api/rest/v4/dockets/1/")
e.message // "courtlistener: HTTP 429: Request was throttled."
e.retry-after // 60
is-not-found
fn (e: Any): Bool
True when e is an HttpError with status 404.
Example
::courtlistener::api/is-not-found({status: 404}) // true
::courtlistener::api/is-not-found({status: 429}) // false
not-json-error
fn (response: ::hot::http/HttpResponse, url: Str): HttpError
An HttpError for a 2xx response that is not JSON, such as a
maintenance page, which would otherwise read as an empty page. Exposed
for testing.
Example
e ::courtlistener::api/not-json-error({status: 200, headers: {}, body: "<html></html>"}, "https://www.courtlistener.com/api/rest/v4/dockets/1/")
e.status // 200
path-segment
fn (value: Any): Str
Percent-encode one path segment.
Example
::courtlistener::api/path-segment("a b") // "a%20b"
query-string
fn (params: Map): Str
Build a ?a=1&b=2 suffix from a Map, dropping null and blank values
(pure); "" when nothing remains.
Example
::courtlistener::api/query-string({court: "dcd", cursor: null}) // "?court=dcd"
::courtlistener::api/query-string({cursor: null}) // ""
request
fn (method: Str, url: Str, headers: Map): ::hot::http/HttpResponse
GET (or another method) a CourtListener URL with headers, returning
the HttpResponse on 2xx or an Err carrying HttpError. A
transport failure passes through as its own Err.
Example
token ::hot::ctx/get("courtlistener.api-token")
headers {Authorization: ::courtlistener/auth-header(token)}
response ::courtlistener::api/request("GET", "https://www.courtlistener.com/api/rest/v4/dockets/4214664/", headers)
response.status
require-api-token
fn (cfg: Map): Str
The API token from resolved settings, or an Err naming where to set it.
Example
cfg ::courtlistener::api/resolve({})
token ::courtlistener::api/require-api-token(cfg)
resolve
fn (opts: Map): Map
Resolve settings for one call: {api-token, base-url}. Values in
opts win over context; an api-token in opts is used for that
call only and comes back unchanged. An Err when api-token is in
opts but blank or null, or when opts has a base-url without
api-token.
Example
cfg ::courtlistener::api/resolve({api-token: ::hot::ctx/get("tenant.courtlistener-token")})
cfg.base-url
Types
HttpError
HttpError type {
source: Str,
status: Int,
url: Str,
headers: Map,
body: Any,
retry-after: Int?,
message: Str
}
A failed CourtListener response. source is "courtlistener";
url the requested URL (the token goes in a header, never the URL);
retry-after the parsed Retry-After seconds on 429s; message a
one-line summary that never includes credentials. status is
normally non-2xx, but it is 200 when the site answered with something
other than JSON (see decode-body).