# Pivo

[![Build Status](https://travis-ci.org/fleetlink/pivo.svg?branch=master)](https://travis-ci.org/github/fleetlink/pivo) [![Hex Version](http://img.shields.io/hexpm/v/pivo.svg?style=flat)](https://hex.pm/packages/pivo)

Pivo is an Elixir interface for the [Pivotal Tracker](https://www.pivotaltracker.com) [REST API V5](https://www.pivotaltracker.com/help/api).

## Installation

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

```elixir
def deps do
  [{:pivo, "~> 0.1"}]
end
```

## Configuration

Pivo needs your Pivotal Tracker API token, by default it reads the `TOKEN` variable from the current environment.

Otherwise you could override the following configuration variables in your `config/config.exs` file.

```elixir
config :pivo,
  api_token: "TOKEN",
  url_base: "https://www.pivotaltracker.com/services/v5"
```

## Usage

The `Pivo` module provides all the methods to access the currently supported endpoints and resources.
Depending on what the underlying API supports, a resource may have the following methods:

| Method Prefix       | Description                                                                    |
| -----------------   | ----------------------------------------------------------                     |
| **get\_all_**       | Returns all of user's resource.                                                |
| **get\_selected_**  | Returns a list of resources given its parent id.                               |
| **get\_paginated_** | Returns a metadata map with a paginated list of resources given its parent id. |
| **fetch_**          | Fetch the content of the specified resource by id.                             |
| **create_**         | Create a resource.                                                             |
| **update_**         | Update a resource.                                                             |
| **destroy_**        | Destroy a resource.                                                            |

### Supported Endpoints

- [x] Account
- [ ] Account Memberships
- [x] Accounts
- [ ] Activity
- [ ] Attachments
- [ ] Blockers
- [x] Comments
- [ ] Epic
- [ ] Epics
- [ ] Exports
- [ ] Iterations
- [ ] Labels
- [x] Me
- [ ] Notifications
- [x] Project
- [ ] Project History
- [ ] Project Integrations
- [ ] Project Memberships
- [ ] Project Webhooks
- [x] Projects
- [ ] Releases
- [ ] Request Aggregator
- [ ] Reviews
- [ ] Search
- [ ] Source Commits
- [x] Stories
- [x] Story
- [ ] Story Tasks
- [ ] Story Transitions
- [ ] Workspaces

## Example

```elixir
iex> Pivo.get_all_projects()
{:ok,
 [
   %Pivo.Resources.Project{id: 1234, ...},
   %Pivo.Resources.Project{...}
 ]}

iex> Pivo.create_story(1234, %{name: "This is a story"})
{:ok,
 %Pivo.Resources.Story{id: 4567, ...}}

iex> Pivo.get_paginated_stories(1234)
{:ok,
 %{
   data: [
     %Pivo.Resources.Story{id: 4567, ...}
   ],
   http_status: "200",
   pagination: %{limit: 100, offset: 0, returned: 1, total: 1},
   project_version: 3
 }}

iex> Pivo.create_comment(1234, 4567, %{text: "This is a comment"})
{:ok,
 %Pivo.Resources.Comment{id: 8900, ...}}

iex> Pivo.get_selected_comments(1234, 4567)
{:ok,
 [
   %Pivo.Resources.Comment{id: 8900, ...}
 ]}

iex> Pivo.update_comment(1234, 4567, 8900, %{text: "This is an updated comment"})
{:ok,
 %Pivo.Resources.Comment{id: 8900, ...}}

iex(3)> Pivo.destroy_comment(1234, 4567, 8900)
{:ok, :no_content}
```

## Copyright and License

Copyright (c) 2020 FLEET-LINK GmbH

The source code is licensed under [The MIT License (MIT)][license]

[license]: https://github.com/fleetlink/pivo/tree/master/LICENSE.md