Unicom360.Client (Unicom360 v0.1.0)

Copy Markdown View Source

A configured, immutable Unicom360 client.

Build one with Unicom360.client/1 (or Unicom360.client!/1) and pass it to every operation. A client is a plain struct: it holds no process and is safe to share between processes and to keep in application config or a module attribute at runtime. put_options/2 returns a copy with other options.

The API key is never shown by inspect/2:

#Unicom360.Client<base_url: "https://api.unicom360.com", api_key: [REDACTED], ...>

Options

  • :api_key - required. Defaults to the :unicom360 application environment, then the UNICOM360_API_KEY environment variable. A missing, empty or blank key is a :configuration_error. An explicit api_key: "" does not fall back to the environment.
  • :base_url - defaults to the application environment, then UNICOM360_BASE_URL, then "https://api.unicom360.com". Must be https; plain http is allowed only for localhost, 127.0.0.0/8 and ::1 (a local mock). A path prefix is kept, trailing slashes are removed, and a query string or fragment is refused.
  • :timeout - milliseconds to wait for the response on each attempt (Req's :receive_timeout). Default 60_000.
  • :connect_timeout - milliseconds to connect, TLS included. Default 10_000.
  • :max_retries - retries after the first attempt. Default 2.
  • :max_retry_wait - the longest single wait between attempts, in milliseconds. Default 60_000. A rate-limit wait longer than this returns the error at once.
  • :auto_reference_ids - give every send without a user_reference_id a generated one, reused on every retry. Default false. See the README.
  • :app_info - %{name: "shopsync", version: "2.3.0", url: "https://shopsync.example"} (version and url optional), appended to the User-Agent.
  • :req_options - extra options for Req.new/1 (for example :finch, :connect_options or a custom :adapter). The SDK always sets retry: false (it retries itself), redirect: false (the API key is never replayed to another host) and its own method, URL, body and headers.
  • :plug - a plug that answers instead of the network, for tests (Req.Test).
  • :clock - a 0-arity function returning the current Unix time in milliseconds. Used for rate-limit waits. Test seam.
  • :sleeper - a 1-arity function taking milliseconds; every retry wait goes through it. Test seam.
  • :random - a 0-arity function returning a float in [0, 1), for jitter. Test seam.

:api_key, :base_url, :timeout, :connect_timeout, :max_retries, :max_retry_wait, :auto_reference_ids, :app_info and :req_options can also be set in the application environment:

# config/runtime.exs
config :unicom360, api_key: System.get_env("UNICOM360_API_KEY")

An option passed to Unicom360.client/1 wins over the application environment, which wins over the environment variables, which win over the defaults. A value of nil, and an environment variable that is empty or blank, count as unset.

Summary

Types

app_info()

%{name: String.t(), version: String.t() | nil, url: String.t() | nil}

option()
t()

Functions

put_options(client, opts)

Returns a copy of the client with some options changed.

Types

app_info()

@type app_info() :: %{
  name: String.t(),
  version: String.t() | nil,
  url: String.t() | nil
}

%{name: String.t(), version: String.t() | nil, url: String.t() | nil}

option()

@type option() ::
  {:api_key, String.t()}
  | {:base_url, String.t()}
  | {:timeout, pos_integer()}
  | {:connect_timeout, pos_integer()}
  | {:max_retries, non_neg_integer()}
  | {:max_retry_wait, non_neg_integer()}
  | {:auto_reference_ids, boolean()}
  | {:app_info, map() | keyword()}
  | {:req_options, keyword()}
  | {:plug, term()}
  | {:clock, (-> integer())}
  | {:sleeper, (non_neg_integer() -> term())}
  | {:random, (-> float())}

t()

@type t() :: %Unicom360.Client{
  api_key: String.t(),
  app_info: app_info() | nil,
  auto_reference_ids: boolean(),
  base_url: String.t(),
  clock: (-> integer()) | nil,
  connect_timeout: pos_integer(),
  max_retries: non_neg_integer(),
  max_retry_wait: non_neg_integer(),
  plug: term(),
  random: (-> float()) | nil,
  req_options: keyword(),
  sleeper: (non_neg_integer() -> term()) | nil,
  timeout: pos_integer(),
  user_agent: String.t()
}

Functions

put_options(client, opts)

@spec put_options(t(), [option()]) :: t()

Returns a copy of the client with some options changed.

Takes the same options as Unicom360.client/1; the ones not given keep their current value (the environment is not read again). Raises Unicom360.Error (:configuration_error) for an unusable option.

fast = Unicom360.Client.put_options(client, timeout: 5_000, max_retries: 0)