phildionne/flinks

# Flinks

A ruby client for the [Flinks](https://flinks.io) API.

[![Maintainability](https://api.codeclimate.com/v1/badges/f7714d9a2a4bd8a58bff/maintainability)](https://codeclimate.com/github/phildionne/flinks/maintainability)
[![Test Coverage](https://api.codeclimate.com/v1/badges/f7714d9a2a4bd8a58bff/test_coverage)](https://codeclimate.com/github/phildionne/flinks/test_coverage)
[![Build Status](https://travis-ci.org/phildionne/flinks.svg?branch=master)](https://travis-ci.org/phildionne/flinks)

## Installation

```bash
gem install flinks
```

Or with bundler:

```ruby
gem 'flinks', require: 'flinks'
```

## Usage

This library needs to be configured with your API customer ID.

```ruby
flinks = Flinks.new(customer_id: ENV['FLINKS_CUSTOMER_ID'])
```

Configure `on_error` to catch API requests returning a `400..599` HTTP status.

```ruby
flinks = Flinks.new({
  customer_id: ENV['FLINKS_CUSTOMER_ID'],
  on_error: Proc.new do |status, message, body|
    p [status, message, body]
  end
})
```

Configure `debug` to print every API requests and responses. Default to `false`.

```ruby
flinks = Flinks.new({
  customer_id: ENV['FLINKS_CUSTOMER_ID'],
  debug: true
})
```

Configure `raw` to get the raw, non-transformed API response. Default to `false`.

```ruby
flinks = Flinks.new({
  customer_id: ENV['FLINKS_CUSTOMER_ID'],
  raw: true
})
```

### Sandbox and Production

By default, the client uses the sandbox API endpoint: `https://toolbox-api.private.fin.ag/v3`. In production, the API endpoint must be configured with your own:

```ruby
flinks = Flinks.new(customer_id: ENV['FLINKS_CUSTOMER_ID'], api_endpoint: "https://YOURNAME-api.private.fin.ag/v3")
```

### Endpoints

#### Authorize

- `authorize(login_id:, options:)`
- `authorize_with_credentials(username:, password:, institution:, options:)`
- `authorize_multiple(login_ids:)`

#### Account

- `accounts_summary(request_id:, options:)`
- `accounts_summary_async(request_id:)`
- `accounts_detail(request_id:, options:)`
- `accounts_detail_async(request_id:)`

#### Card

- `delete_card(card_id:)`

#### Refresh

- `set_scheduled_refresh(activated, login_id:)`

#### Statement

- `statements(options:)`
- `statements_async(request_id:)`

## Errors

### Client Errors

| Error                          | Description                                                            |
|:-------------------------------|:-----------------------------------------------------------------------|
| `Flinks::ClientError`          | Raised when API returns a 400..499 HTTP status code                    |
| `Flinks::BadRequest`           | Raised when API returns a 400 HTTP status code                         |
| `Flinks::Unauthorized`         | Raised when API returns a 401 HTTP status code                         |
| `Flinks::Forbidden`            | Raised when API returns a 403 HTTP status code                         |
| `Flinks::TooManyRequests`      | Raised when API returns a 403 HTTP status code for rate limit exceeded |
| `Flinks::NotFound`             | Raised when API returns a 404 HTTP status code                         |
| `Flinks::MethodNotAllowed`     | Raised when API returns a 405 HTTP status code                         |
| `Flinks::NotAcceptable`        | Raised when API returns a 406 HTTP status code                         |
| `Flinks::Conflict`             | Raised when API returns a 409 HTTP status code                         |
| `Flinks::UnsupportedMediaType` | Raised when API returns a 415 HTTP status code                         |
| `Flinks::UnprocessableEntity`  | Raised when API returns a 422 HTTP status code                         |

### Server Errors

| Error                         | Description                                         |
|:------------------------------|:----------------------------------------------------|
| `Flinks::ServerError`         | Raised when API returns a 500..599 HTTP status code |
| `Flinks::InternalServerError` | Raised when API returns a 500 HTTP status code      |
| `Flinks::NotImplemented`      | Raised when API returns a 501 HTTP status code      |
| `Flinks::BadGateway`          | Raised when API returns a 502 HTTP status code      |
| `Flinks::ServiceUnavailable`  | Raised when API returns a 503 HTTP status code      |

## Documentation

See the [API docs](https://docs.flinks.io/reference/flinks-api).

## Supported Ruby versions

- MRI 2.3
- MRI 2.4
- MRI 2.5

## Development

Run all tests:

```bash
bundle exec rspec
```

## License

[MIT](LICENSE.txt)