A stateful session wrapper around Weavr.Config + Weavr.Auth.
weavr supports two ways of managing the per-user auth_token:
Stateless — you call
Weavr.Authfunctions directly with aWeavr.Configand pass theauth_tokenyou got back explicitly into every subsequent resource call. This is the right choice in a web app backend, where the token belongs to an HTTP session or a database row, not to a long-lived Elixir process.Stateful (Weavr.Client) — start one
Weavr.ClientGenServer per logged-in user (e.g. one per LiveView process, or one per long-running worker acting as a single Weavr user). The client holds the current Auth/Access Token and automatically attaches it to every call made through Weavr.Client.request/2, refreshing or re-exchanging it as needed.
Resource modules (Weavr.Accounts, Weavr.Cards, ...) accept either
a Weavr.Config struct or a Weavr.Client pid/name — when given a
Weavr.Client, they fetch the current token from it; when given a
bare Weavr.Config, they expect you to also pass the token
explicitly. See each resource module's docs for its exact function
signatures.
Example — stateful usage
{:ok, client} =
Weavr.Client.start_link(
api_key: System.fetch_env!("WEAVR_API_KEY"),
environment: :sandbox
)
:ok = Weavr.Client.login_with_password(client, email: "a@b.com", password: "secret")
{:ok, accounts} = Weavr.Accounts.list(client)Example — stateless usage
config = Weavr.Config.new(api_key: "...", environment: :sandbox)
{:ok, %{auth_token: token}} = Weavr.Auth.login_with_password(config, email: "a@b.com", password: "secret")
{:ok, accounts} = Weavr.Accounts.list(config, token)Summary
Functions
Returns a child spec, so a Weavr.Client can be placed directly under a supervision tree.
Returns the Weavr.Config the client was started with. Resource
modules use this to issue requests against the right base URL.
Returns the currently stored token, or {:error, :not_authenticated}
if no login has happened yet. Resource modules use this internally;
you generally won't need to call it directly.
Lists identities available to the client's current Auth Token.
Logs in via biometrics. See Weavr.Auth.login_via_biometrics/2.
Logs in with email/password and stores the resulting Auth Token on the client for use by subsequent requests.
Logs out and clears the stored token.
Exchanges the client's current Auth Token for an Access Token scoped
to identity_id, storing the result. See the multi-identity
discussion in Weavr.Auth.
Starts a Weavr.Client process.
Runs a resource-module function with the client's config and current
token, in one call. This is what Weavr.Accounts.list/1 and similar
one-arity resource functions use internally when given a
Weavr.Client instead of a {config, token} pair.
Types
@type t() :: pid() | GenServer.name()
Functions
Returns a child spec, so a Weavr.Client can be placed directly under a supervision tree.
@spec config(t()) :: Weavr.Config.t()
Returns the Weavr.Config the client was started with. Resource
modules use this to issue requests against the right base URL.
Returns the currently stored token, or {:error, :not_authenticated}
if no login has happened yet. Resource modules use this internally;
you generally won't need to call it directly.
@spec list_identities(t()) :: {:ok, [map()]} | {:error, Weavr.Error.t()}
Lists identities available to the client's current Auth Token.
@spec login_via_biometrics(t(), map()) :: :ok | {:error, Weavr.Error.t()}
Logs in via biometrics. See Weavr.Auth.login_via_biometrics/2.
@spec login_with_password(t(), keyword() | map()) :: :ok | {:error, Weavr.Error.t()}
Logs in with email/password and stores the resulting Auth Token on the client for use by subsequent requests.
@spec logout(t()) :: :ok | {:error, Weavr.Error.t()}
Logs out and clears the stored token.
@spec select_identity(t(), String.t()) :: :ok | {:error, Weavr.Error.t()}
Exchanges the client's current Auth Token for an Access Token scoped
to identity_id, storing the result. See the multi-identity
discussion in Weavr.Auth.
@spec start_link(keyword()) :: GenServer.on_start()
Starts a Weavr.Client process.
Accepts the same options as Weavr.Config.new/1, plus any
GenServer.start_link/3 option (:name, etc).
@spec with_token(t(), (Weavr.Config.t(), String.t() -> result)) :: result | {:error, :not_authenticated} when result: var
Runs a resource-module function with the client's config and current
token, in one call. This is what Weavr.Accounts.list/1 and similar
one-arity resource functions use internally when given a
Weavr.Client instead of a {config, token} pair.