Twittex

v0.3.6

Twittex v0.3.6 Twittex.Client.Base View Source

A behaviour module for implementing your own Twitter client.

Provides convenience functions for working with Twitter’s RESTful API. You can use get/3 and post/4using a relative url pointing to the API endpoint.

Example

To create your own client, create a new module and use Twittex.Client.Base as follow:

defmodule TwitterBot do
  use Twittex.Client.Base

  def search(term, options \ []) do
    get "/search/tweets.json?" <> URI.encode_query(Keyword.merge(%{q: term}, options))
  end
end

This client works as a singleton and can be added to a supervisor tree:

Supervisor.start_link([TwittexBot.child_spec], strategy: :one_for_one)

And here’s how you may use it:

TwitterBot.search "#myelixirstatus", count: 3

Authentication

Twittex supports following OAuth authentication methods:

To request an access token with one of the method listed above. See get_token/1 and get_token/3. Here’s, a brief example for application-only authentication:

iex> token = Twittex.Client.Base.get_token!
%OAuth2.AccessToken{...}

Under the hood, the Twittex.Client.Base module uses HTTPoison.Base and overrides the request/5 method to pass the authentication headers along the request.

Link to this section Summary

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor

get(pid, url, headers \\ [], options \\ [])

Issues a GET request to the given url

get!(pid, url, headers \\ [], options \\ [])

Same as get/4 but raises HTTPoison.Error if an error occurs during the request

get_token(options \\ [])

Returns a OAuth2 application-only token

get_token(token, token_secret, options \\ [])

Returns a OAuth1 token for the given token and token_secret

get_token!(options \\ [])

Same as get_token/1 but raises OAuth2.Error if an error occurs during the request

get_token!(token, token_secret, options \\ [])

Same as get_token/3 but raises HTTPoison.Error if an error occurs during the request

init(arg1)

Invoked when the server is started. start_link/3 or start/3 will block until it returns

post(pid, url, body \\ [], headers \\ [], options \\ [])

Issues a POST request to the given url

post!(pid, url, body, headers \\ [], options \\ [])

Same as post/5 but raises HTTPoison.Error if an error occurs during the request

stage(pid, method, url, body \\ [], headers \\ [], options \\ [])

Streams data from the given url

stage!(pid, method, url, body \\ [], headers \\ [], options \\ [])

Same as stage/6 but raises HTTPoison.Error if an error occurs during the request

Link to this section Functions

Link to this function child_spec(arg) View Source

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function get(pid, url, headers \\ [], options \\ []) View Source 
get(pid(), String.t(), List.t(), Keyword.t()) ::
  {:ok, %{}} | {:error, HTTPoison.Error.t()}

Issues a GET request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

Link to this function get!(pid, url, headers \\ [], options \\ []) View Source 
get!(pid(), String.t(), List.t(), Keyword.t()) :: %{}

Same as get/4 but raises HTTPoison.Error if an error occurs during the request.

Link to this function get_token(options \\ []) View Source 
get_token(Keyword.t()) ::
  {:ok, OAuth2.AccessToken.t()} | {:error, OAuth2.Error.t()}

Returns a OAuth2 application-only token.

With application-only authentication you don’t have the context of an authenticated user and this means that accessing APIs that require user context, will not work.

Link to this function get_token(token, token_secret, options \\ []) View Source 
get_token(String.t(), String.t(), Keyword.t()) ::
  {:ok, OAuther.Credentials.t()} | {:error, HTTPoison.Error.t()}

Returns a OAuth1 token for the given token and token_secret.

Link to this function get_token!(options \\ []) View Source 
get_token!(Keyword.t()) :: OAuth2.AccessToken.t()

Same as get_token/1 but raises OAuth2.Error if an error occurs during the request.

Link to this function get_token!(token, token_secret, options \\ []) View Source 
get_token!(String.t(), String.t(), Keyword.t()) :: OAuther.Credentials.t()

Same as get_token/3 but raises HTTPoison.Error if an error occurs during the request.

Link to this function init(arg1) View Source

Invoked when the server is started. start_link/3 or start/3 will block until it returns.

args is the argument term (second argument) passed to start_link/3.

Returning {:ok, state} will cause start_link/3 to return {:ok, pid} and the process to enter its loop.

Returning {:ok, state, timeout} is similar to {:ok, state} except handle_info(:timeout, state) will be called after timeout milliseconds if no messages are received within the timeout.

Returning {:ok, state, :hibernate} is similar to {:ok, state} except the process is hibernated before entering the loop. See c:handle_call/3 for more information on hibernation.

Returning :ignore will cause start_link/3 to return :ignore and the process will exit normally without entering the loop or calling c:terminate/2. If used when part of a supervision tree the parent supervisor will not fail to start nor immediately try to restart the GenServer. The remainder of the supervision tree will be (re)started and so the GenServer should not be required by other processes. It can be started later with Supervisor.restart_child/2 as the child specification is saved in the parent supervisor. The main use cases for this are:

  • The GenServer is disabled by configuration but might be enabled later.
  • An error occurred and it will be handled by a different mechanism than the Supervisor. Likely this approach involves calling Supervisor.restart_child/2 after a delay to attempt a restart.

Returning {:stop, reason} will cause start_link/3 to return {:error, reason} and the process to exit with reason reason without entering the loop or calling c:terminate/2.

Callback implementation for GenServer.init/1.

Link to this function post(pid, url, body \\ [], headers \\ [], options \\ []) View Source 
post(pid(), String.t(), binary(), List.t(), Keyword.t()) ::
  {:ok, %{}} | {:error, HTTPoison.Error.t()}

Issues a POST request to the given url.

Link to this function post!(pid, url, body, headers \\ [], options \\ []) View Source 
post!(pid(), String.t(), binary(), List.t(), Keyword.t()) :: %{}

Same as post/5 but raises HTTPoison.Error if an error occurs during the request.

Link to this function stage(pid, method, url, body \\ [], headers \\ [], options \\ []) View Source 
stage(pid(), Atom.t(), String.t(), binary(), List.t(), Keyword.t()) ::
  {:ok, GenStage.t()} | {:error, HTTPoison.Error.t()}

Streams data from the given url.

Link to this function stage!(pid, method, url, body \\ [], headers \\ [], options \\ []) View Source 
stage!(pid(), Atom.t(), String.t(), binary(), List.t(), Keyword.t()) ::
  Twittex.Client.Stream.t()

Same as stage/6 but raises HTTPoison.Error if an error occurs during the request.