# ExTrello [![Build Status](]([![Coverage Status](]([![](]([![ Downloads](]([![Deps Status](]([![Inline docs](](

A library for interfacing with the Trello API.

Heavily influenced by with some stuff straight ripped out of it.

## **Important! Migration from 0.x -> 1.x**
Since this change will break all existing projects using ExTrello upon upgrading this deserves a spot at the top :)

All calls to the Trello API will now be wrapped in a tuple with the first element either being `:ok`, `:error`, or `:connection_error`
Regular errors will no longer raise exceptions as that is not idiomatic.

Here's an example(just a little sample):
# Old and bad
boards = ExTrello.boards()
# New and great
{:ok, boards} = ExTrello.boards()

# Old and bad, yuck!
try do
  %ExTrello.Error{code: code, message: message} -> IO.puts "ERROR[#{code}] - #{message}"

# New and fantastic
case ExTrello.get("potato/2") do
  {:ok, response} -> response
  {:error, %ExTrello.Error{code: code, message: message}} -> IO.puts "ERROR[#{code}] - #{message}"
  {:connection_error, %ExTrello.ConnectionError{reason: _, message: message}} -> IO.puts "#{message} We should retry."

## Documentation

## Installation

  1. Add `ex_trello` to your list of dependencies in `mix.exs`:

    def deps do
        {:ex_trello, "~> 1.1.0"}

  2. Ensure `ex_trello` is started before your application:

    def application do
      [applications: [:ex_trello]]
  3. Run `mix deps.get`

## Usage
1. Make sure you've completed [installation.](#installation)
2. Use `ExTrello.configure` to setup Trello's OAuth authentication parameters.
3. Call functions in the `ExTrello` module. (e.g. `ExTrello.boards()`)

### Configuration
The default behavior is for ExTrello to use the application environment:

In `config/<env>.exs` add:

# I like using ENV vars to populate my configuration. But fill this out however you'd like :)
config :ex_trello, :oauth, [
  consumer_key:    System.get_env("TRELLO_CONSUMER_KEY"),
  consumer_secret: System.get_env("TRELLO_CONSUMER_SECRET"),
  token:           System.get_env("TRELLO_ACCESS_TOKEN"),
  token_secret:    System.get_env("TRELLO_ACCESS_SECRET")

You can also manually configure it at runtime:
ExTrello.configure(consumer_key: "...", ...)

You can also configure for the current process only:
defmodule TrelloServer do
  use GenServer

  def start_link(user) do
    GenServer.start_link(__MODULE__, user, [])

  def init(%User{token: token, token_secret: token_secret}) do
    :ok = ExTrello.configure(
      consumer_key: System.get_env("TRELLO_CONSUMER_KEY"),
      consumer_secret: System.get_env("TRELLO_CONSUMER_SECRET"),
      token: token,
      token_secret: token_secret
    {:ok, %{boards: []}}

  # Rest of your code...

## Samples

#### Authorize your application

Example for authorization. This is a naive solution that only works for demonstration.
TODO: Set up example application.
# First we have to get a request token from Trello.
{:ok, token} = ExTrello.request_token("http://localhost:4000/auth/trello/callback/1234")
# We have to store this token because we need the `oauth_token_secret` after the callback to obtain our access token & secret.
# e.g."1234", token.oauth_token_secret)

# Generate the url for authorization
{:ok, auth_url} = ExTrello.authorize_url(token.oauth_token, %{return_url: "http://localhost:4000/auth/trello/callback/1234", scope: "read,write", expiration: "never", name: "Your Application Name here"})

# Copy the url and visit it using your browser.
IO.puts auth_url
After signing in/authorizing the application you will be redirected to the callback URL you specified in the Request token & authorize URL.


Copy the `oauth_token` and `oauth_verifier` above:
oauth_token = "copied_oauth_token"
oauth_verifier = "copied_oauth_verifier"
oauth_token_secret = retrieve_oauth_token_secret_from_before() # e.g. TokenAgent.retrieve("1234") from hypothetical TokenAgent

{:ok, access_token} = ExTrello.access_token(oauth_verifier, oauth_token, oauth_token_secret)

# Let's configure ExTrello with our newly obtained access token
  consumer_key: System.get_env("TRELLO_CONSUMER_KEY"),
  consumer_secret: System.get_env("TRELLO_CONSUMER_SECRET"),
  token: access_token.oauth_token,
  token_secret: access_token.oauth_token_secret

# Testing our token!
{:ok, member} = ExTrello.member() # Fetches the authenticated member record from Trello

## TODO:
- [ ] Add models for ~~label~~, ~~checklist~~, ~~member~~, notification, ~~organization~~, session, token, ~~action~~
- [ ] Pagination
- [ ] Code Cleanup! (Perhaps remove `defapicall` macro and use the `with` keyword instead? Have to evaluate.)
- [ ] Example Application
- [ ] Investigate handling storage of request_token.oauth_token_secret instead of leaving that up to the dev.