ex_trello v1.0.0 ExTrello

Provides access interface to the Trello API.

Summary

Functions

Fetch action associated with action_id

GET OAuthAuthorizeToken

GET OAuthAuthorizeToken

Fetch board with board_id

Fetch board with board_id. See reference for list of options

Fetch cards associated to %ExTrello.Model.Board{} or board id

Fetch cards associated to %ExTrello.Model.Board{} or board id. See reference for detailed list of options

Fetch all boards of authenticated user

Fetch all boards of authenticated user. See reference for detailed list of options

Fetch all boards of given username or Trello User ID. See reference for detailed list of options

Fetch card associated with given id or shortlink

Fetch card associated with given id or shortlink with options. See reference for detailed list of options

Gets checklist using specified id

Gets checklist using specified id. See reference for detailed list of options

Gets board that given checklist or checklist id belongs to

Provides OAuth configuration settings for accessing trello server

Provides OAuth configuration settings for accessing trello server

Create board with supplied name

Create board with supplied name. See reference for detailed list of options

Create a card for a given %List{} or list id

Create a card for a given %List{} or list id using provided options. See reference for detailed list of options

Create a comment on a given card

Creates list on specified board using id or struct with specified name

Creates list on specified board using id or struct with specified name. See reference for detailed list of options

DELETE request to Trello

Edit board with supplied field values. See reference for detailed list of options

Edit a card. A comprehensive list of all properties that can be passed can be found in the reference

Edits list using specified id or struct with fields

GET request to Trello

Fetch list associated with list_id or %List{} struct

Fetch list associated with list_id or %List{} struct and options. See reference for detailed list of options

Fetch the authenticated member

Fetch the authenticated member. See reference for list of options

POST request to Trello

PUT request to Trello

GET OAuthGetRequestToken

Functions

access_token(verifier, request_token, request_token_secret)

Specs

access_token(String.t, String.t, String.t) ::
  {:ok, ExTrello.Model.AccessToken.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

GET OAuthGetAccessToken

Examples

{:ok, access_token} = ExTrello.access_token("OAUTH_VERIFIER", "OAUTH_TOKEN", "OAUTH_TOKEN_SECRET")
action(action_id)

Specs

action(String.t) ::
  {:ok, ExTrello.Model.Action.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Fetch action associated with action_id.

Examples

{:ok, action} = ExTrello.action("57a5108615c475280d511795")

Reference

https://developers.trello.com/advanced-reference/action#actions-idaction

authorize_url(oauth_token)

Specs

authorize_url(String.t) ::
  {:ok, String.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

GET OAuthAuthorizeToken

Examples

{:ok, request_token} = ExTrello.request_token
{:ok, authorize_url} = ExTrello.authorize_url(request_token.oauth_token)

Returns the URL you should redirect the user to for authorization

authorize_url(oauth_token, options)

Specs

authorize_url(String.t, Keyword.t | Map.t) ::
  {:ok, String.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

GET OAuthAuthorizeToken

Examples

{:ok, request_token} = ExTrello.request_token("http://localhost:4000/auth/trello/callback/1234")
{:ok, authorize_url} = ExTrello.authorize_url(request_token.oauth_token, return_url: "http://localhost:4000/auth/trello/callback/1234", scope: "read,write", expiration: "never", name: "Example Authentication")

Returns the URL you should redirect the user to for authorization

board(id)

Specs

board(String.t) ::
  {:ok, ExTrello.Model.Board.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Fetch board with board_id.

Examples

{:ok, board} = ExTrello.board("57663306e4b15193fcc97483")

Reference

https://developers.trello.com/advanced-reference/board#get-1-boards-board-id

board(id, options)

Specs

board(String.t, Keyword.t) ::
  {:ok, ExTrello.Model.Board.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Fetch board with board_id. See reference for list of options.

Examples

# Fetching a board with an invalid id
{:error, 400, "invalid id"} = ExTrello.board("123")

# Board with options
{:ok, board_with_options} = ExTrello.board("57663306e4b15193fcc97483", [actions_display: true])

Reference

https://developers.trello.com/advanced-reference/board#get-1-boards-board-id

board_cards(board_or_id)

Specs

board_cards(String.t | ExTrello.Model.Board.t) ::
  {:ok, [ExTrello.Model.Card.t]} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Fetch cards associated to %ExTrello.Model.Board{} or board id.

Examples

# Using a board_id
{:ok, cards} = ExTrello.board_cards("57663306e4b15193fcc97483")

# Using a Board struct (Useful in case you're passing this struct around, you should just use the `cards: "all"` flag to fetch a board and its cards in the same request)
# {:ok, board} = %ExTrello.Model.Board{id: "57663306e4b15193fcc97483" blah blah blah}
board |> ExTrello.board_cards

Reference

https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-cards

board_cards(board_or_id, options)

Specs

board_cards(String.t | ExTrello.Model.Board.t, Keyword.t) ::
  {:ok, [ExTrello.Model.Card.t]} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Fetch cards associated to %ExTrello.Model.Board{} or board id. See reference for detailed list of options.

Examples

# Using a board_id
{:ok, cards} = ExTrello.board_cards("57663306e4b15193fcc97483", attachments: true, checklists: "all")

# Using a Board struct (Useful in case you're passing this struct around, you should just use the `cards: "all"` flag to fetch a board and its cards in the same request)
# {:ok, board} = %ExTrello.Model.Board{id: "57663306e4b15193fcc97483" blah blah blah}
board |> ExTrello.board_cards(members: true)

Reference

https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-cards

boards()

Specs

boards ::
  {:ok, [ExTrello.Model.Board.t]} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Fetch all boards of authenticated user.

Examples

{:ok, boards} = ExTrello.boards()
boards(options)

Specs

boards(Keyword.t) ::
  {:ok, [ExTrello.Model.Board.t]} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Fetch all boards of authenticated user. See reference for detailed list of options.

Examples

{:ok, boards_with_options} = ExTrello.boards([filter: "pinned,public", fields: "shortLink,subscribed"])

Reference

https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username-boards

boards(user, options)

Specs

boards(String.t, Keyword.t) ::
  {:ok, [ExTrello.Model.Board.t]} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Fetch all boards of given username or Trello User ID. See reference for detailed list of options.

Examples

{:ok, trello_user_boards} = ExTrello.boards("trello")

Reference

https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username-boards

card(card_id_or_shortlink)

Specs

card(String.t) ::
  {:ok, ExTrello.Model.Card.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Fetch card associated with given id or shortlink.

Examples

# Using card id
{:ok, card} = ExTrello.card("56e8fa38abbbdd74b978c3cd")

# Using shortlink
{:ok, card} = ExTrello.card("JyUbYknO")

Reference

https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink

card(card_id_or_shortlink, options)

Specs

card(String.t, Keyword.t) ::
  {:ok, ExTrello.Model.Card.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Fetch card associated with given id or shortlink with options. See reference for detailed list of options.

Examples

{:ok, %ExTrello.Model.Card{list: %ExTrello.Model.List{}}} = ExTrello.card("JyUbYknO", list: true)

Reference

https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink

checklist(id)

Specs

checklist(String.t) ::
  {:ok, ExTrello.Model.Checklist.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Gets checklist using specified id.

Examples

{:ok, checklist} = ExTrello.checklist("57bc918bfb1103f1d32ffe01")

Reference

https://developers.trello.com/advanced-reference/checklist#get-1-checklists-idchecklist

checklist(id, options)

Specs

checklist(String.t, Keyword.t) ::
  {:ok, ExTrello.Model.Checklist.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Gets checklist using specified id. See reference for detailed list of options.

Examples

{:ok, checklist} = ExTrello.checklist("57bc918bfb1103f1d32ffe01", cards: "all")

Reference

https://developers.trello.com/advanced-reference/checklist#get-1-checklists-idchecklist

checklist_board(id_or_struct)

Specs

checklist_board(String.t | ExTrello.Model.Checklist.t) ::
  {:ok, ExTrello.Model.Board.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Gets board that given checklist or checklist id belongs to.

Examples

# Using id
{:ok, board} = ExTrello.checklist_board("57bc918bfb1103f1d32ffe01")

# Using %Checklist{}
ExTrello.checklist("57bc918bfb1103f1d32ffe01")
|> elem(1)
|> ExTrello.checklist_board

Reference

https://developers.trello.com/advanced-reference/checklist#get-1-checklists-idchecklist-board

configure(oauth)

Specs

configure(Keyword.t) :: :ok

Provides OAuth configuration settings for accessing trello server.

The specified configuration applies globally. Use ExTrello.configure/2 for setting different configurations on each processes.

Examples

ExTrello.configure(
  app_key: System.get_env("TRELLO_APP_KEY"),
  app_secret: System.get_env("TRELLO_APP_SECRET"),
  access_token: System.get_env("TRELLO_ACCESS_TOKEN"),
  access_token_secret: System.get_env("TRELLO_ACCESS_SECRET")
)
configure(scope, oauth)

Specs

configure(:global | :process, Keyword.t) :: :ok

Provides OAuth configuration settings for accessing trello server.

Options

The scope can have one of the following values.

  • :global - configuration is shared for all processes.

  • :process - configuration is isolated for each process.

Examples

ExTrello.configure(
  :process,
  app_key: System.get_env("TRELLO_APP_KEY"),
  app_secret: System.get_env("TRELLO_APP_SECRET"),
  access_token: System.get_env("TRELLO_ACCESS_TOKEN"),
  access_token_secret: System.get_env("TRELLO_ACCESS_SECRET")
)
create_board(name)

Specs

create_board(String.t) ::
  {:ok, ExTrello.Model.Board.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Create board with supplied name.

Examples

{:ok, board} = ExTrello.create_board("TrelloHub")

Reference

https://developers.trello.com/advanced-reference/board#post-1-boards

create_board(name, options)

Specs

create_board(String.t, Keyword.t) ::
  {:ok, ExTrello.Model.Board.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Create board with supplied name. See reference for detailed list of options.

Examples

{:ok, board} = ExTrello.create_board("TrelloHub", desc: "An application to synchronize your Trello boards with your GitHub activity.", powerups: "all")

Reference

https://developers.trello.com/advanced-reference/board#post-1-boards

create_card(list_or_id, name)

Specs

create_card(String.t | ExTrello.Model.List.t, String.t) ::
  {:ok, ExTrello.Model.Card.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Create a card for a given %List{} or list id.

Examples

{:ok, board} = ExTrello.board("57663306e4b15193fcc97483", lists: "all")
{:ok, %ExTrello.Model.List{id: id}} = List.first(board.lists) # This happens to be my Icebox list
{:ok, card} = ExTrello.create_card(id, "Should definitely improve documentation and tests for this project.")

Reference

https://developers.trello.com/advanced-reference/card#post-1-cards

create_card(list_or_id, name, options)

Specs

Create a card for a given %List{} or list id using provided options. See reference for detailed list of options.

Examples

{:ok, board} = ExTrello.board("57663306e4b15193fcc97483", lists: "all", members: "all")

{:ok, card} =
  List.first(board.lists) # This happens to be my Icebox list
  |> ExTrello.create_card("This card will be at the top of the list.", pos: "top", idMembers: Enum.map(board.members, &(&1.id)) |> Enum.join(","))

Reference

https://developers.trello.com/advanced-reference/card#post-1-cards

create_comment(card_or_id_or_shortlink, text)

Specs

create_comment(String.t | ExTrello.Model.Card.t, String.t) ::
  {:ok, ExTrello.Model.Action.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Create a comment on a given card.

Examples

{:ok, action} = ExTrello.create_comment("JyUbYknO", "Passed code review, moving this to the `Complete` list.")

Reference

https://developers.trello.com/advanced-reference/card#post-1-cards-card-id-or-shortlink-actions-comments

create_list(board_id_or_struct, name)

Specs

create_list(String.t | ExTrello.Model.Board.t, String.t) ::
  {:ok, ExTrello.Model.List.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Creates list on specified board using id or struct with specified name.

Examples

# Using board id
{:ok, list} = ExTrello.create_list("57663306e4b15193fcc97483", "The name of the list")

# Using board struct
{:ok, board} = ExTrello.board("57663306e4b15193fcc97483")
# Do some stuff with the board... then you wanna create a list

{:ok, created_list} = ExTrello.create_list(board, "Also the name of a list")

Reference

https://developers.trello.com/advanced-reference/list#post-1-lists

create_list(board_id_or_struct, name, options)

Specs

Creates list on specified board using id or struct with specified name. See reference for detailed list of options.

Examples

# Using board id
{:ok, list} = ExTrello.create_list("57663306e4b15193fcc97483", "The name of the list", pos: "top")

# Using board struct
{:ok, board} = ExTrello.board("57663306e4b15193fcc97483")
# Do some stuff with the board... then you wanna create a list

{:ok, copied_list} = ExTrello.create_list(board, "Also the name of a list", idListSource: "some_list_id")

Reference

https://developers.trello.com/advanced-reference/list#post-1-lists

delete(path)

DELETE request to Trello

Examples

{:ok, response} = ExTrello.delete("boards/57ae3940f43e6d960e0c45da/powerUps/calendar")
delete(path, params)

Specs

delete(String.t, Keyword.t) ::
  {:ok, String.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

See ExTrello.API.BareRequests.delete/2.

edit_board(id, options)

Specs

edit_board(String.t, Keyword.t) ::
  {:ok, ExTrello.Model.Board.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Edit board with supplied field values. See reference for detailed list of options.

Examples

# Capture the id of our newly created board.
{:ok, %ExTrello.Model.Board{id: id}} = ExTrello.create_board("Some name")
# Let's edit the name of our new board.
{:ok, edited_board} = ExTrello.edit_board(id, name: "Another name entirely.")

Reference

https://developers.trello.com/advanced-reference/board#put-1-boards-board-id

edit_card(card_or_id_or_shortlink, properties_to_edit)

Specs

Edit a card. A comprehensive list of all properties that can be passed can be found in the reference.

Examples

# Using ID
{:ok, card} = ExTrello.edit_card("56e8fa38abbbdd74b978c3cd", name: "A different name now.", desc: "Honestly does anyone even read these?", pos: "top", idList: "57663322ac7d147b2c337e34")

# Using Shortlink
{:ok, card} = ExTrello.edit_card("JyUbYknO", closed: true, subscribed: false)

# Using a %ExTrello.Model.Card{} struct
ExTrello.card("JyUbYknO")
|> elem(1)
|> ExTrello.edit_card(name: "I passed an ExTrello.Model.Card struct to the function to edit this card.")

Reference

https://developers.trello.com/advanced-reference/card#put-1-cards-card-id-or-shortlink

edit_list(list_id_or_struct, fields)

Specs

Edits list using specified id or struct with fields

Examples

# Using id {:ok, edited_list} = ExTrello.edit_list(“57b619a0e1714100f54bc33c”, name: “Ridiculous Ideas”)

# Using struct ExTrello.list(“57b619a0e1714100f54bc33c”) |> elem(1) |> ExTrello.edit_list(name: “Pipes ahoy”)

Reference

https://developers.trello.com/advanced-reference/list#put-1-lists-idlist

get(path)

GET request to Trello

Examples

{:ok, response} = ExTrello.get("boards/57ae3940f43e6d960e0c45da/boardStars", filter: "mine")
get(path, params)

Specs

get(String.t, Keyword.t) ::
  {:ok, String.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

See ExTrello.API.BareRequests.get/2.

list(id_or_struct)

Specs

Fetch list associated with list_id or %List{} struct

Examples

# Using id
{:ok, list} = ExTrello.list("57663322ac7d147b2c337e34")

# Using a struct
{:ok, list} = ExTrello.list(%ExTrello.Model.List{...})

Reference

https://developers.trello.com/advanced-reference/list#get-1-lists-idlist

list(id_or_struct, options)

Fetch list associated with list_id or %List{} struct and options. See reference for detailed list of options.

Examples

{:ok, list_with_options} = ExTrello.list("57663322ac7d147b2c337e34", board: true, fields: "all")

Reference

https://developers.trello.com/advanced-reference/list#get-1-lists-idlist

member()

Specs

member ::
  {:ok, ExTrello.Model.Member.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Fetch the authenticated member.

Examples

{:ok, member} = ExTrello.member()

Reference

https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username

member(options)

Specs

member(Keyword.t) ::
  {:ok, ExTrello.Model.Member.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

Fetch the authenticated member. See reference for list of options.

Examples

{:ok, member_with_organizations} = ExTrello.member(organizations: "all")

Reference

https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username

post(path)

POST request to Trello

Examples

{:ok, response} = ExTrello.post("boards/57ae3940f43e6d960e0c45da/lists", name: "Best List", pos: "top")
post(path, params)

Specs

post(String.t, Keyword.t) ::
  {:ok, String.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

See ExTrello.API.BareRequests.post/2.

put(path)

PUT request to Trello

Examples

{:ok, response} = ExTrello.put("boards/57ae3940f43e6d960e0c45da/labelNames/blue", value: "Bluey")
put(path, params)

Specs

put(String.t, Keyword.t) ::
  {:ok, String.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

See ExTrello.API.BareRequests.put/2.

request_token(return_url)

Specs

request_token(String.t) ::
  {:ok, ExTrello.Model.RequestToken.t} |
  {:error, ExTrello.Error.t} |
  {:connection_error, ExTrello.ConnectionError.t}

GET OAuthGetRequestToken

Examples

{:ok, request_token} = ExTrello.request_token("http://localhost:4000/auth/trello/callback/1234")

Reference

https://trello.com/app-key

start(type, args)

false