@spec httpc_http(map()) :: {:ok, map()} | {:error, term()}

The default HTTP function, backed by OTP's own :httpc.

Using :httpc is what lets this library ship with Jason as its only runtime dependency — adding it to a project pulls in no HTTP stack. Pass :http to KYCCentral.new/1 to use Req, Finch, Tesla or anything else instead.

Retries are handled by this module rather than the transport, so the policy matches the Python and JavaScript clients. Bodies are returned undecoded and decoded centrally, so an injected function and the default behave identically.

@spec names_body([String.t()], pos_integer() | nil) ::
  {:ok, map()} | {:error, KYCCentral.Error.t()}

Build the %{"names" => [...]} body used by the batch screening endpoints.

@spec query_string(keyword() | nil) :: String.t()

Encode query parameters, dropping unset ones and repeating list values.

Built by hand rather than through URI.encode_query/1 because several endpoints take repeatable parameters (confirmed_media_url, company_status), which need ?k=a&k=b rather than one comma-joined value.

@spec request(KYCCentral.t(), :get | :post, String.t(), keyword()) ::
  {:ok, term()} | {:error, KYCCentral.Error.t()}

Issue a request, retrying transient failures.

Returns the decoded body on success, or {:error, %KYCCentral.Error{}}.

@spec segment(term(), String.t()) ::
  {:ok, String.t()} | {:error, KYCCentral.Error.t()}

Validate and percent-encode a value being interpolated into a URL path.

Empty segments would silently collapse the path onto a different endpoint, and officer ids are opaque upstream tokens, so both are checked and encoded.