TreasuryPrime.HTTP (TreasuryPrime v1.0.0)

Copy Markdown View Source

Internal HTTP orchestration layer shared by every resource module. Not part of the public API — use the resource modules (TreasuryPrime.Account, TreasuryPrime.Ach, etc.) instead.

Responsibilities:

  • Building the full request URL (joining client.base_url with a path, or using an already-absolute URL verbatim — used for pagination's page_next links).
  • HTTP Basic Auth (api_key_id / api_key_value).
  • JSON encoding the request body and decoding the response body.
  • Translating non-2xx responses and transport failures into TreasuryPrime.Error structs.
  • Automatic retries with exponential backoff + jitter for 429 and transient 5xx responses.
  • Emitting :telemetry events (no-op if :telemetry isn't loaded).
  • Attaching the X-Idempotency-Key header when requested.

Summary

Types

method()

Functions

request(client, method, path_or_url, body \\ nil, opts \\ [])

Performs an authenticated request against the Treasury Prime API and returns {:ok, decoded_body} or {:error, %TreasuryPrime.Error{}}.

request!(client, method, path_or_url, body \\ nil, opts \\ [])

Like request/5, but raises a TreasuryPrime.Error on failure instead of returning {:error, error}. Used to implement every resource module's ! variant (e.g. TreasuryPrime.Account.get!/2).

upload(client, path, binary, content_type)

Uploads raw binary content (used only by TreasuryPrime.File.upload/3, which is the one Treasury Prime endpoint that takes a raw file body instead of JSON).

Types

method()

@type method() :: :get | :post | :patch | :put | :delete

Functions

request(client, method, path_or_url, body \\ nil, opts \\ [])

@spec request(TreasuryPrime.Client.t(), method(), String.t(), map() | nil, keyword()) ::
  {:ok, term()} | {:error, TreasuryPrime.Error.t()}

Performs an authenticated request against the Treasury Prime API and returns {:ok, decoded_body} or {:error, %TreasuryPrime.Error{}}.

path_or_url may be a path relative to client.base_url (e.g. "ach" or "account/acct_123") or an already-absolute URL (used internally for pagination, since page_next is returned as a full URL by the API).

Options

  • :query - a map of query string parameters (only meaningful for :get/:delete).
  • :idempotency_key - sent as X-Idempotency-Key.
  • :headers - extra headers, list of {String.t(), String.t()}.

request!(client, method, path_or_url, body \\ nil, opts \\ [])

@spec request!(TreasuryPrime.Client.t(), method(), String.t(), map() | nil, keyword()) ::
  term()

Like request/5, but raises a TreasuryPrime.Error on failure instead of returning {:error, error}. Used to implement every resource module's ! variant (e.g. TreasuryPrime.Account.get!/2).

upload(client, path, binary, content_type)

@spec upload(TreasuryPrime.Client.t(), String.t(), binary(), String.t()) ::
  {:ok, term()} | {:error, TreasuryPrime.Error.t()}

Uploads raw binary content (used only by TreasuryPrime.File.upload/3, which is the one Treasury Prime endpoint that takes a raw file body instead of JSON).