Transport for SEC IAPD: the settings resolver (per-call opts first,
then context variables, then the default), a typed HttpError, and
GETs that return a response or decoded JSON.
| opts key | Context variable | Default |
|---|---|---|
user-agent | sec.iapd.user-agent | hot-dev-sec-iapd-pkg/0.1 (+https://hot.dev) |
Per-call User-Agent. user-agent in opts is masked in call
records and never written to context. Present but blank or null, it
is an error, never a fallback to context.
Context Vars
sec.iapd.user-agent
Values
DEFAULT_USER_AGENT
DEFAULT_USER_AGENT: Str "hot-dev-sec-iapd-pkg/0.1 (+https://hot.dev)"
SOURCE
SOURCE: Str "sec-iapd"
Functions
get-json
fn (url: Str, headers: Map): Any
GET a JSON resource and return the decoded body, or an Err carrying
HttpError.
Example
body ::sec::iapd::api/get-json(
::sec::iapd/firm-url(174673),
::sec::iapd::api/headers({})
)
body.hits.total
given
fn (v: Any): Bool
True for a non-null value that is not a blank string.
Example
::sec::iapd::api/given("x") // true
::sec::iapd::api/given(" ") // false
::sec::iapd::api/given(null) // false
headers
fn (opts: Map): Map
The request headers from settings, or an Err from resolve.
Example
h ::sec::iapd::api/headers({user-agent: "Acme Research ops@acme.example"})
h.User-Agent
http-error
fn (response: ::hot::http/HttpResponse, url: Str): HttpError
Build an HttpError from a non-2xx response (pure).
Example
url "https://api.adviserinfo.sec.gov/search/firm/1"
response ::hot::http/HttpResponse({status: 404, headers: {}, body: ""})
::sec::iapd::api/http-error(response, url).status // 404
::sec::iapd::api/http-error(response, url).message
// "sec-iapd: HTTP 404 for https://api.adviserinfo.sec.gov/search/firm/1"
json-body
fn (response: ::hot::http/HttpResponse): Any
Decode a response's JSON. The reports host serves its index as
binary/octet-stream, so this reads the bytes when the body isn't
already decoded (pure).
Example
response ::hot::http/HttpResponse({status: 200, headers: {}, body: "{\"total\": 1}"})
::sec::iapd::api/json-body(response) // {total: 1}
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
::sec::iapd::api/query-string({query: "Acme", start: null}) // "?query=Acme"
::sec::iapd::api/query-string({query: " "}) // ""
request
fn (url: Str, headers: Map): ::hot::http/HttpResponse
GET a URL with headers, returning the HttpResponse on 2xx or an
Err carrying HttpError. A transport failure passes through as its
own Err.
Example
response ::sec::iapd::api/request(
::sec::iapd/reports-index-url(),
::sec::iapd::api/headers({})
)
response.status
resolve
fn (opts: Map): Map
Resolve settings for one call: {user-agent}. A value in opts wins
over context and is used for that call only. An Err when user-agent
is in opts but blank or null.
Example
cfg ::sec::iapd::api/resolve({user-agent: "Tenant Co ops@tenant.example"})
Types
HttpError
HttpError type {
source: Str,
status: Int,
url: Str,
message: Str
}
A non-2xx response. source is "sec-iapd"; url the requested URL
(these hosts take no credentials); message a one-line summary that
never includes the User-Agent.