Xero.HTTP.Client (Xero v1.0.0)

Core HTTP client for all Xero API requests.

Handles:

Authenticated requests with Bearer token injection
Automatic token refresh on 401 responses
Rate limit header tracking and Retry-After respect
Telemetry emission for every request
JSON encode/decode (transparent)
Request ID injection (x-correlation-id)
If-Modified-Since header injection for incremental sync
Multi-part form posting for OAuth token endpoints

Summary

Types

method()

opts()

raw_result()

Raw {:ok, adapter_response} | {:error, term()} as returned by the underlying Req call.

response()

Normalised HTTP response shape used internally, regardless of adapter (Req/Finch).

result()

Functions

delete(url, token, extra_headers \\ [], opts \\ [])

Authenticated DELETE request.

get(url, token, extra_headers \\ [], opts \\ [])

Authenticated GET request.

post(url, body, token, extra_headers \\ [], opts \\ [])

Authenticated POST request with JSON body.

post_form(url, body, extra_headers \\ [], opts \\ [])

Form-encoded POST for OAuth token endpoints (no auth token required).

put(url, body, token, extra_headers \\ [], opts \\ [])

Authenticated PUT request with JSON body.

Types

method()

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

opts()

@type opts() :: [
  tenant_id: String.t() | nil,
  skip_tenant: boolean(),
  accept: String.t(),
  if_modified_since: DateTime.t() | String.t() | nil,
  params: map() | keyword()
]

raw_result()

@type raw_result() :: {:ok, map()} | {:error, term()}

Raw {:ok, adapter_response} | {:error, term()} as returned by the underlying Req call.

response()

@type response() :: %{
  status: pos_integer(),
  body: term(),
  headers: [{String.t(), String.t()}]
}

Normalised HTTP response shape used internally, regardless of adapter (Req/Finch).

result()

@type result() :: {:ok, response()} | {:error, Xero.Error.t()}

Functions

delete(url, token, extra_headers \\ [], opts \\ [])

@spec delete(String.t(), Xero.Auth.Token.t(), list(), opts()) :: result()

Authenticated DELETE request.

get(url, token, extra_headers \\ [], opts \\ [])

@spec get(String.t(), Xero.Auth.Token.t(), list(), opts()) :: result()

Authenticated GET request.

post(url, body, token, extra_headers \\ [], opts \\ [])

@spec post(String.t(), term(), Xero.Auth.Token.t(), list(), opts()) :: result()

Authenticated POST request with JSON body.

post_form(url, body, extra_headers \\ [], opts \\ [])

@spec post_form(String.t(), map(), list(), opts()) :: result()

Form-encoded POST for OAuth token endpoints (no auth token required).

put(url, body, token, extra_headers \\ [], opts \\ [])

@spec put(String.t(), term(), Xero.Auth.Token.t(), list(), opts()) :: result()

Authenticated PUT request with JSON body.