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 keyContext variableDefault
api-tokencourtlistener.api-tokennone: token-gated calls fail without it
base-urlcourtlistener.base-urlhttps://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

Optional
  • courtlistener.api-token
  • courtlistener.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).