Magpie.Client (Magpie v0.8.0)

Holds the credentials used to authenticate every request.

A client is a plain struct — build one and pass it to any Magpie function. There are three ways to build it:

# 1. A static access token. Simplest, but Dropbox access tokens expire
#    in about 4 hours — fine for scripts, not for daemons.
client = Magpie.Client.new("ACCESS_TOKEN")

# 2. A refresh token. Magpie starts a linked `Magpie.Auth.TokenServer`
#    and keeps the access token fresh for you.
client = Magpie.Client.new(refresh_token: rt, app_key: key, app_secret: secret)
client = Magpie.Client.new(refresh_token: rt, app_key: key, pkce: true)

# 3. A token provider you supervise (or wrote) yourself.
client = Magpie.Client.new(token_provider: {Magpie.Auth.TokenServer, MyApp.DropboxToken})
client = Magpie.Client.new(token_provider: {MyApp.DropboxTokens, "user-42"})

Form 2 links the token server to the calling process, which is convenient in scripts and iex, but in an application you usually want the server in your supervision tree — see Magpie.Auth.TokenServer and the OAuth guide.

Whatever the form, the credentials end up behind a Magpie.Auth.TokenProvider stored in token_provider.

Summary

Types

access_token()

m()

provider()

t()

Functions

missing_scopes(client, required)

Lists missing scopes from caller-supplied grants, or returns :unknown.

new()

Builds a client with no credentials.

new(access_token)

Builds a client from an access token, a refresh token or a token provider.

new(token, opts)

Builds a static-token client with its own request settings.

token_provider(client)

Returns the {module, arg} token provider a client authenticates with.

with_options(client, opts)

Returns a client with merged configuration; the original is unchanged.

Types

access_token()

@type access_token() :: binary()

m()

@type m() :: %Magpie.Client{
  access_token: term(),
  config: term(),
  deadline: term(),
  token_provider: term()
}

provider()

@type provider() :: {module(), term()}

t()

@type t() :: %Magpie.Client{
  access_token: access_token() | nil,
  config: keyword(),
  deadline: integer() | nil,
  token_provider: provider() | nil
}

Functions

missing_scopes(client, required)

@spec missing_scopes(t(), [String.t()]) :: [String.t()] | :unknown

Lists missing scopes from caller-supplied grants, or returns :unknown.

Uses the scope list supplied by the caller. It does not contact Dropbox or block requests.

new()

@spec new() :: m()

Builds a client with no credentials.

iex> Magpie.Client.new()
%Magpie.Client{access_token: nil, token_provider: nil}

new(access_token)

@spec new(access_token() | keyword()) :: t()

Builds a client from an access token, a refresh token or a token provider.

Examples

iex> client = Magpie.Client.new("ACCESS_TOKEN")
iex> client.token_provider
{Magpie.Auth.StaticToken, "ACCESS_TOKEN"}

iex> client = Magpie.Client.new(token_provider: {Magpie.Auth.TokenServer, MyApp.DropboxToken})
iex> client.token_provider
{Magpie.Auth.TokenServer, MyApp.DropboxToken}

With :refresh_token, a Magpie.Auth.TokenServer is started and linked to the calling process. Token options (:name, :refresh_margin, :on_refresh, ...) are forwarded to it; :oauth_req_options configures its HTTP calls separately from the client's file-request :req_options:

client =
  Magpie.Client.new(
    refresh_token: System.fetch_env!("DROPBOX_REFRESH_TOKEN"),
    app_key: System.fetch_env!("DROPBOX_APP_KEY"),
    app_secret: System.fetch_env!("DROPBOX_APP_SECRET")
  )

new(token, opts)

@spec new(binary(), keyword()) :: t()

Builds a static-token client with its own request settings.

token_provider(client)

@spec token_provider(struct()) :: provider()

Returns the {module, arg} token provider a client authenticates with.

Clients built by hand (%Magpie.Client{access_token: "..."}) fall back to Magpie.Auth.StaticToken.

iex> Magpie.Client.token_provider(%Magpie.Client{access_token: "ACCESS_TOKEN"})
{Magpie.Auth.StaticToken, "ACCESS_TOKEN"}

with_options(client, opts)

@spec with_options(t(), keyword()) :: t()

Returns a client with merged configuration; the original is unchanged.

Supports :req_options, :retry (false or a keyword list), :timeout (execution budget in milliseconds or :infinity), :base_url, :upload_url, :notify_url, :account_id (a local diagnostic label), and :scopes (a list of known granted scopes, or nil when unknown).

Precedence is operation > client > application > defaults. :req_options merge by key; :retry replaces the entire policy. Request configuration does not reconfigure an independently supervised OAuth token provider. See the configuration guide for budget semantics.