Transport for the FFIEC CDR Public Web Service: the settings resolver (per-call opts first, then context variables, then defaults), a typed HttpError, and GETs. The service takes every parameter as a request header, so there are no query strings.

opts keyContext variableDefault
user-idffiec.user-idnone: calls fail without it
tokenffiec.tokennone: calls fail without it
base-urlffiec.base-urlhttps://ffieccdr.azure-api.us/public

Per-call credentials. user-id and token in opts are masked in call records and never written to context, and they go together: one without the other is an error, so a call never pairs one tenant's user with another's token. Present but blank or null, either is an error, never a fallback to context. A per-call base-url needs both in the same opts: context credentials are never sent to a per-call URL.

Context Vars

Optional
  • ffiec.user-id
  • ffiec.token
  • ffiec.base-url

Values

BASE_URL

BASE_URL: Str "https://ffieccdr.azure-api.us/public"

CREDENTIAL_KEYS

CREDENTIAL_KEYS: Vec [
  "user-id",
  "token"
]

PACKAGE_AGENT

PACKAGE_AGENT: Str "hot-dev-ffiec-pkg/0.1 (+https://hot.dev)"

SOURCE

SOURCE: Str "ffiec"

Functions

auth-headers

fn (cfg: Map): Map

The UserID and Authentication headers from resolved settings (pure), or an Err naming what to set. Authentication is the service's own header, not Authorization, and carries Bearer {token}. A token already starting with Bearer is used as it is.

Example

headers ::ffiec::api/auth-headers({
  user-id: ::hot::ctx/get("ffiec.user-id"),
  token: ::hot::ctx/get("ffiec.token")
})
headers.UserID

decode-list

fn (response: ::hot::http/HttpResponse): Any

The list in a response (pure): [] for an empty one, such as a 204, and the decoded rows otherwise.

Example

::ffiec::api/decode-list({status: 200, headers: {}, body: "[1474309, 540739]"})  // [1474309, 540739]
::ffiec::api/decode-list({status: 204, headers: {}, body: null})                 // []

get-list

fn (url: Str, headers: Map): Any

GET a list resource and return its rows, or an Err carrying HttpError.

Example

headers ::ffiec::api/auth-headers(::ffiec::api/resolve({}))
rows ::ffiec::api/get-list("https://ffieccdr.azure-api.us/public/RetrieveUBPRReportingPeriods", headers)
last(rows)

given

fn (v: Any): Bool

True for a non-null value that is not a blank string.

Example

::ffiec::api/given("  ")  // false
::ffiec::api/given("x")   // true

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

response {status: 403, headers: {}, body: {StatusCode: 403, Message: "Rate limit exceeded"}}
e ::ffiec::api/http-error(response, "https://ffieccdr.azure-api.us/public/RetrieveReportingPeriods")
e.status   // 403
e.message  // "ffiec: HTTP 403: Rate limit exceeded"

request

fn (url: Str, headers: Map): ::hot::http/HttpResponse

GET url with headers, returning the HttpResponse on 2xx or an Err carrying HttpError. A transport failure passes through as its own Err.

Example

response ::ffiec::api/request("https://ffieccdr.azure-api.us/public/RetrieveUBPRReportingPeriods", {
  UserID: ::hot::ctx/get("ffiec.user-id"),
  Authentication: `Bearer ${::hot::ctx/get("ffiec.token")}`
})
response.body

resolve

fn (opts: Map): Map

Resolve settings for one call: {user-id, token, base-url}. Values in opts win over context; credentials in opts are used for that call only and come back unchanged. An Err when a credential is in opts but blank or null, when opts has one credential without the other, or when it has base-url without both.

Example

cfg ::ffiec::api/resolve({
  user-id: ::hot::ctx/get("tenant.ffiec-user"),
  token: ::hot::ctx/get("tenant.ffiec-token")
})
cfg.base-url

Types

HttpError

HttpError type {
    source: Str,
    status: Int,
    url: Str,
    headers: Map,
    body: Any,
    retry-after: Int?,
    message: Str
}

A non-2xx FFIEC response. source is "ffiec"; url the requested URL (credentials travel in headers, never the URL); retry-after the parsed Retry-After seconds when the response has one; message a one-line summary that never includes credentials.