View Source ExPipedrive.Oauth (ex_pipedrive v0.1.0)

Pipedrive OAuth helpers: authorize URL, code exchange, and token refresh.

Token exchange and refresh return ExPipedrive.Oauth.Token bundles (access, refresh, expiry, scope, api_domain). Persist them via ExPipedrive.Oauth.TokenStore in host apps — core has no Ecto dependency.

Legacy helpers get_refresh_token/4 and refresh_access_token/3 still return bare token strings for transitional callers.

Summary

Types

option()

Options that may be passed to a request function. See request/2 for detailed descriptions.

Functions

authorization_url(client_id, redirect_url, state \\ "")

delete(client, url, opts)

Perform a DELETE request.

delete!(client, url, opts)

Perform a DELETE request.

ensure_fresh(token, client_id, client_secret, opts \\ [])

Returns a fresh token, refreshing when Token.expired?/2 is true.

exchange_authorization_code(auth_code, client_id, client_secret, redirect_url, opts \\ [])

Exchanges an authorization code for a full Token bundle.

get(client, url, opts)

Perform a GET request.

get!(client, url, opts)

Perform a GET request.

get_refresh_token(auth_code, client_id, client_secret, redirect_url)

Exchanges an auth code and returns only the refresh token string.

head(client, url, opts)

Perform a HEAD request.

head!(client, url, opts)

Perform a HEAD request.

options(client, url, opts)

Perform a OPTIONS request.

options!(client, url, opts)

Perform a OPTIONS request.

patch(client, url, body, opts)

Perform a PATCH request.

patch!(client, url, body, opts)

Perform a PATCH request.

post(client, url, body, opts)

Perform a POST request.

post!(client, url, body, opts)

Perform a POST request.

put(client, url, body, opts)

Perform a PUT request.

put!(client, url, body, opts)

Perform a PUT request.

refresh(refresh_token, client_id, client_secret, opts \\ [])

Refreshes an access token, returning a full Token bundle.

refresh_access_token(refresh_token, client_id, client_secret)

Refreshes and returns only the access token string.

request(client \\ %Tesla.Client{}, options)

Perform a request.

request!(client \\ %Tesla.Client{}, options)

Perform request and raise in case of error.

trace(client, url, opts)

Perform a TRACE request.

trace!(client, url, opts)

Perform a TRACE request.

Types

option()

@type option() ::
  {:method, Tesla.Env.method()}
  | {:url, Tesla.Env.url()}
  | {:query, Tesla.Env.query()}
  | {:headers, Tesla.Env.headers()}
  | {:body, Tesla.Env.body()}
  | {:opts, Tesla.Env.opts()}

Options that may be passed to a request function. See request/2 for detailed descriptions.

Functions

authorization_url(client_id, redirect_url, state \\ "")

delete(client, url, opts)

@spec delete(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a DELETE request.

See request/1 or request/2 for options definition.

delete("/users")
delete("/users", query: [scope: "admin"])
delete(client, "/users")
delete(client, "/users", query: [scope: "admin"])
delete(client, "/users", body: %{name: "Jon"})

delete!(client, url, opts)

@spec delete!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a DELETE request.

See request!/1 or request!/2 for options definition.

delete!("/users")
delete!("/users", query: [scope: "admin"])
delete!(client, "/users")
delete!(client, "/users", query: [scope: "admin"])
delete!(client, "/users", body: %{name: "Jon"})

ensure_fresh(token, client_id, client_secret, opts \\ [])

@spec ensure_fresh(ExPipedrive.Oauth.Token.t(), String.t(), String.t(), keyword()) ::
  {:ok, ExPipedrive.Oauth.Token.t()} | {:error, ExPipedrive.Error.t()}

Returns a fresh token, refreshing when Token.expired?/2 is true.

Options: :skew_seconds (default 60), :adapter, :token_url, :default_api_domain (defaults to token.api_domain on refresh).

exchange_authorization_code(auth_code, client_id, client_secret, redirect_url, opts \\ [])

@spec exchange_authorization_code(
  String.t(),
  String.t(),
  String.t(),
  String.t(),
  keyword()
) ::
  {:ok, ExPipedrive.Oauth.Token.t()} | {:error, ExPipedrive.Error.t()}

Exchanges an authorization code for a full Token bundle.

get(client, url, opts)

@spec get(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a GET request.

See request/1 or request/2 for options definition.

get("/users")
get("/users", query: [scope: "admin"])
get(client, "/users")
get(client, "/users", query: [scope: "admin"])
get(client, "/users", body: %{name: "Jon"})

get!(client, url, opts)

@spec get!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a GET request.

See request!/1 or request!/2 for options definition.

get!("/users")
get!("/users", query: [scope: "admin"])
get!(client, "/users")
get!(client, "/users", query: [scope: "admin"])
get!(client, "/users", body: %{name: "Jon"})

get_refresh_token(auth_code, client_id, client_secret, redirect_url)

Exchanges an auth code and returns only the refresh token string.

Prefer exchange_authorization_code/4 for new code.

head(client, url, opts)

@spec head(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a HEAD request.

See request/1 or request/2 for options definition.

head("/users")
head("/users", query: [scope: "admin"])
head(client, "/users")
head(client, "/users", query: [scope: "admin"])
head(client, "/users", body: %{name: "Jon"})

head!(client, url, opts)

@spec head!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a HEAD request.

See request!/1 or request!/2 for options definition.

head!("/users")
head!("/users", query: [scope: "admin"])
head!(client, "/users")
head!(client, "/users", query: [scope: "admin"])
head!(client, "/users", body: %{name: "Jon"})

options(client, url, opts)

@spec options(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a OPTIONS request.

See request/1 or request/2 for options definition.

options("/users")
options("/users", query: [scope: "admin"])
options(client, "/users")
options(client, "/users", query: [scope: "admin"])
options(client, "/users", body: %{name: "Jon"})

options!(client, url, opts)

@spec options!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a OPTIONS request.

See request!/1 or request!/2 for options definition.

options!("/users")
options!("/users", query: [scope: "admin"])
options!(client, "/users")
options!(client, "/users", query: [scope: "admin"])
options!(client, "/users", body: %{name: "Jon"})

patch(client, url, body, opts)

@spec patch(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.result()

Perform a PATCH request.

See request/1 or request/2 for options definition.

patch("/users", %{name: "Jon"})
patch("/users", %{name: "Jon"}, query: [scope: "admin"])
patch(client, "/users", %{name: "Jon"})
patch(client, "/users", %{name: "Jon"}, query: [scope: "admin"])

patch!(client, url, body, opts)

@spec patch!(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a PATCH request.

See request!/1 or request!/2 for options definition.

patch!("/users", %{name: "Jon"})
patch!("/users", %{name: "Jon"}, query: [scope: "admin"])
patch!(client, "/users", %{name: "Jon"})
patch!(client, "/users", %{name: "Jon"}, query: [scope: "admin"])

post(client, url, body, opts)

@spec post(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.result()

Perform a POST request.

See request/1 or request/2 for options definition.

post("/users", %{name: "Jon"})
post("/users", %{name: "Jon"}, query: [scope: "admin"])
post(client, "/users", %{name: "Jon"})
post(client, "/users", %{name: "Jon"}, query: [scope: "admin"])

post!(client, url, body, opts)

@spec post!(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a POST request.

See request!/1 or request!/2 for options definition.

post!("/users", %{name: "Jon"})
post!("/users", %{name: "Jon"}, query: [scope: "admin"])
post!(client, "/users", %{name: "Jon"})
post!(client, "/users", %{name: "Jon"}, query: [scope: "admin"])

put(client, url, body, opts)

@spec put(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.result()

Perform a PUT request.

See request/1 or request/2 for options definition.

put("/users", %{name: "Jon"})
put("/users", %{name: "Jon"}, query: [scope: "admin"])
put(client, "/users", %{name: "Jon"})
put(client, "/users", %{name: "Jon"}, query: [scope: "admin"])

put!(client, url, body, opts)

@spec put!(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a PUT request.

See request!/1 or request!/2 for options definition.

put!("/users", %{name: "Jon"})
put!("/users", %{name: "Jon"}, query: [scope: "admin"])
put!(client, "/users", %{name: "Jon"})
put!(client, "/users", %{name: "Jon"}, query: [scope: "admin"])

refresh(refresh_token, client_id, client_secret, opts \\ [])

@spec refresh(String.t(), String.t(), String.t(), keyword()) ::
  {:ok, ExPipedrive.Oauth.Token.t()} | {:error, ExPipedrive.Error.t()}

Refreshes an access token, returning a full Token bundle.

Pass default_api_domain: when the refresh response omits api_domain so the previous tenant domain is preserved.

refresh_access_token(refresh_token, client_id, client_secret)

Refreshes and returns only the access token string.

Prefer refresh/3 for new code.

request(client \\ %Tesla.Client{}, options)

@spec request(Tesla.Env.client(), [option()]) :: Tesla.Env.result()

Perform a request.

Options

:method - the request method, one of [:head, :get, :delete, :trace, :options, :post, :put, :patch]
:url - either full url e.g. "http://example.com/some/path" or just "/some/path" if using Tesla.Middleware.BaseUrl
:query - a keyword list of query params, e.g. [page: 1, per_page: 100]
:headers - a keyworld list of headers, e.g. [{"content-type", "text/plain"}]
:body - depends on used middleware:
- by default it can be a binary
- if using e.g. JSON encoding middleware it can be a nested map
- if adapter supports it it can be a Stream with any of the above
:opts - custom, per-request middleware or adapter options

Examples

ExampleApi.request(method: :get, url: "/users/path")

# use shortcut methods
ExampleApi.get("/users/1")
ExampleApi.post(client, "/users", %{name: "Jon"})

request!(client \\ %Tesla.Client{}, options)

@spec request!(Tesla.Env.client(), [option()]) :: Tesla.Env.t() | no_return()

Perform request and raise in case of error.

This is similar to request/2 behaviour from Tesla 0.x

See request/2 for list of available options.

trace(client, url, opts)

@spec trace(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a TRACE request.

See request/1 or request/2 for options definition.

trace("/users")
trace("/users", query: [scope: "admin"])
trace(client, "/users")
trace(client, "/users", query: [scope: "admin"])
trace(client, "/users", body: %{name: "Jon"})

trace!(client, url, opts)

@spec trace!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a TRACE request.

See request!/1 or request!/2 for options definition.

trace!("/users")
trace!("/users", query: [scope: "admin"])
trace!(client, "/users")
trace!(client, "/users", query: [scope: "admin"])
trace!(client, "/users", body: %{name: "Jon"})