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 keyContext variableDefault
user-agentsec.iapd.user-agenthot-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

Optional
  • 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.