kentaa-api 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ebca7b73a3ae49b7d9948211b21638e7131340fe58f6b34551260853dd4b6fb
-  data.tar.gz: cc9a8b5450c1b4068867a2bf0eada220174e3d107ae2369ddbc5080bcf785257
+  metadata.gz: 23a4a4487aa472a316b501c6828a794dc7adb49a401142f81380e876db16e38b
+  data.tar.gz: 64237a805e5dfb9631acffeede977b9db625c1768233276d21b573f02926c6c6
 SHA512:
-  metadata.gz: 2815897919718da19a9ed6ddb05589523b492639427fced920168bb469c794a83c5cc4477f9dc3403e7a932f6d88d657035a741f5cb3a44c075807b88b3ccf0f
-  data.tar.gz: 696d64f0bf684fafcbf1c38c24f3f1b03c97312f2c6b666054464b85b58b0907eb27e8a42bffd4e886d035475daaab8e22354af9a39ce9ea9a54943fbd225962
+  metadata.gz: b6efd4d9df769a58d90865c636782cc16ee3c84d2eebf66387cbd9a9758dbc2d534ad3fd33a975f6481b6ded97448a5249449427f619de9c033bc10e201100f2
+  data.tar.gz: a773cebe9d89d3d230d34e37f47e35af40a28815070bf8d5212f5fee83c208663ce0fb8664a211c0b523a091ef8df5d453ca7d17c4616fd967b2486c3be5dc9e

data/.rubocop.yml

@@ -2,12 +2,16 @@
 
 require:
   - rubocop-performance
+  - rubocop-rake
   - rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 2.3
+  NewCops: enable
+  TargetRubyVersion: 2.4
   DisplayCopNames: true
   DisplayStyleGuide: true
+  Exclude:
+    - 'vendor/**/*'
 
 Layout/LineLength:
   Enabled: false
@@ -27,6 +31,9 @@ Metrics/CyclomaticComplexity:
 Metrics/MethodLength:
   Enabled: false
 
+Metrics/PerceivedComplexity:
+  Enabled: false
+
 RSpec/DescribedClass:
   Enabled: false
 

data/.travis.yml

@@ -3,10 +3,9 @@ sudo: false
 cache: bundler
 before_install:
   - gem update --system
-  - gem install bundler -v '< 2'
 rvm:
-  - 2.3.8
-  - 2.4.9
-  - 2.5.7
-  - 2.6.5
-  - 2.7.0
+  - 2.4.10
+  - 2.5.9
+  - 2.6.7
+  - 2.7.3
+  - 3.0.1

data/Gemfile

@@ -5,6 +5,7 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in kentaa-api.gemspec
 gemspec
 
-gem 'rubocop', '~> 0.80.1'
-gem 'rubocop-performance', '~> 1.5.2'
-gem 'rubocop-rspec', '~> 1.38.1'
+gem 'rubocop', '~> 1.12.0'
+gem 'rubocop-performance', '~> 1.10.2'
+gem 'rubocop-rake', '~> 0.5.1'
+gem 'rubocop-rspec', '~> 2.2.0'

data/Gemfile.lock

@@ -1,25 +1,25 @@
 PATH
   remote: .
   specs:
-    kentaa-api (0.4.0)
+    kentaa-api (0.5.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     addressable (2.5.2)
       public_suffix (>= 2.0.2, < 4.0)
-    ast (2.4.0)
+    ast (2.4.2)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
     diff-lcs (1.3)
     hashdiff (0.3.7)
-    jaro_winkler (1.5.4)
-    parallel (1.19.1)
-    parser (2.7.0.4)
-      ast (~> 2.4.0)
+    parallel (1.20.1)
+    parser (3.0.0.0)
+      ast (~> 2.4.1)
     public_suffix (3.0.3)
     rainbow (3.0.0)
-    rake (12.3.3)
+    rake (13.0.3)
+    regexp_parser (2.1.1)
     rexml (3.2.4)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
@@ -34,21 +34,28 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
     rspec-support (3.8.0)
-    rubocop (0.80.1)
-      jaro_winkler (~> 1.5.1)
+    rubocop (1.12.0)
       parallel (~> 1.10)
-      parser (>= 2.7.0.1)
+      parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
       rexml
+      rubocop-ast (>= 1.2.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 1.7)
-    rubocop-performance (1.5.2)
-      rubocop (>= 0.71.0)
-    rubocop-rspec (1.38.1)
-      rubocop (>= 0.68.1)
-    ruby-progressbar (1.10.1)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.4.1)
+      parser (>= 2.7.1.5)
+    rubocop-performance (1.10.2)
+      rubocop (>= 0.90.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rake (0.5.1)
+      rubocop
+    rubocop-rspec (2.2.0)
+      rubocop (~> 1.0)
+      rubocop-ast (>= 1.1.0)
+    ruby-progressbar (1.11.0)
     safe_yaml (1.0.4)
-    unicode-display_width (1.6.1)
+    unicode-display_width (2.0.0)
     webmock (2.3.2)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
@@ -58,14 +65,15 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 1.14)
+  bundler (~> 2.0)
   kentaa-api!
-  rake (~> 12.3)
+  rake (~> 13.0)
   rspec (~> 3.0)
-  rubocop (~> 0.80.1)
-  rubocop-performance (~> 1.5.2)
-  rubocop-rspec (~> 1.38.1)
+  rubocop (~> 1.12.0)
+  rubocop-performance (~> 1.10.2)
+  rubocop-rake (~> 0.5.1)
+  rubocop-rspec (~> 2.2.0)
   webmock (~> 2.3, >= 2.3.2)
 
 BUNDLED WITH
-   1.17.3
+   2.2.3

data/README.md

@@ -4,7 +4,28 @@
 [![Build Status](https://travis-ci.org/KentaaNL/kentaa-api.svg?branch=master)](https://travis-ci.org/KentaaNL/kentaa-api)
 [![Code Climate](https://codeclimate.com/github/KentaaNL/kentaa-api/badges/gpa.svg)](https://codeclimate.com/github/KentaaNL/kentaa-api)
 
-This gem provides a Ruby library for communicating with the [Kentaa API](https://api.kentaa.nl/v1/doc).
+This gem provides a Ruby library for communicating with the [Kentaa API](https://developer.kentaa.nl/kentaa-api/).
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Actions](#actions)
+  - [Donation forms](#donation-forms)
+  - [Donations](#donations)
+  - [Manual donations](#manual-donations)
+  - [Newsletter subscriptions](#newsletter-subscriptions)
+  - [Projects](#projects)
+  - [Recurring donors](#recurring-donors)
+  - [Segments](#segments)
+  - [Sites](#sites)
+  - [Teams](#teams)
+  - [Users](#users)
+  - [Pagination](#pagination)
+- [Error handling](#error-handling)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 
@@ -24,9 +45,7 @@ Or install it yourself as:
 
 ## Usage
 
-### Initialization
-
-Create the client with your API key:
+Create a Kentaa API configuration and client using your API key:
 
 ```ruby
 require 'kentaa/api'
@@ -35,132 +54,367 @@ config = Kentaa::Api::Config.new('your_api_key')
 client = Kentaa::Api::Client.new(config)
 ```
 
-### Retrieving data
+The configuration is created for the production environment by default. If you want to use the testing environment, then add `test: true`:
 
-All endpoints use the same convention for retrieving data. The method `list` is for retrieving multiple resources. The method `get` is used for retrieving a single resource.
+```ruby
+config = Kentaa::Api::Config.new('your_api_key', test: true)
+```
 
-The `list` method on the endpoint returns an [Enumerable](https://ruby-doc.org/core/Enumerable.html) object:
+### Actions
 
 ```ruby
-actions = client.actions.list
-
-actions.each { |a| puts a.title }
-actions.first
+# List Actions
+actions = client.actions.list  # paginated
+actions = client.actions.all   # non-paginated
+
+actions.each do |action|
+  action.title  # => "Lorem ipsum"
+  action.url  # => "https://demo1.kentaa.nl/actie/john-doe"
+end
+
+# Get Action by ID or slug
+action = client.actions.get(1)
+action = client.actions.get("john-doe")
+
+action.title  # => "Lorem ipsum"
+action.url  # => "https://demo1.kentaa.nl/actie/john-doe"
+
+# Create a new Action
+action = client.actions.create(
+  title: "Lorem ipsum",
+  description: "Dolorum animi qui nihil iure dolore velit.",
+  owner_id: 1
+)
+
+action.id  # => 1
+action.title  # => "Lorem ipsum"
+action.description  # => "Dolorum animi qui nihil iure dolore velit."
+action.owner  # => Kentaa::Api::Resources::User
+
+# Update an Action
+action = client.actions.update(1, title: "Foobar")
+
+action.title  # => "Foobar"
 ```
 
-The results might be part of a paginated set. You can query the next page by doing:
+See also the [Kentaa API docs](https://developer.kentaa.nl/kentaa-api/#actions) and [Kentaa::Api::Resources::Action](lib/kentaa/api/resources/action.rb) for all available properties.
+
+### Donation forms
 
 ```ruby
-actions = actions.next if actions.next_page?
+# List Donation forms
+donation_forms = client.donation_forms.list  # paginated
+donation_forms = client.donation_forms.all   # non-paginated
+
+donation_forms.each do |form|
+  form.title  # => "Lorem ipsum dolor sit amet"
+  form.url  # => "https://demo1.kentaa.nl/form"
+end
+
+# Get Donation form
+form = client.donation_forms.get(1)
+
+form.title  # => "Lorem ipsum dolor sit amet"
+form.owner  # => Kentaa::Api::Resources::User
+form.url  # => "https://demo1.kentaa.nl/form"
+form.total_amount  # => BigDecimal("95.0")
 ```
 
-See also `Kentaa::Api::Resources::List` for the available methods for pagination.
+See also the [Kentaa API docs](https://developer.kentaa.nl/kentaa-api/#donation-forms) and [Kentaa::Api::Resources::DonationForm](lib/kentaa/api/resources/donation_form.rb) for all available properties.
 
-The `all` method on the endpoint returns an [Enumerator](https://ruby-doc.org/core/Enumerator.html) and will iterate automatically through all pages to retrieve the requested data.
+### Donations
 
 ```ruby
-actions = client.actions.all
-
-actions.each { |a| puts a.title }
-actions.first(100)
+# List Donations
+donations = client.donations.list  # paginated
+donations = client.donations.all   # non-paginated
+
+donations.each do |donations|
+  donation.first_name  # => "John"
+  donation.last_name  # => "Doe"
+end
+
+# Get Donation
+donation = client.donations.get(1)
+
+donation.first_name  # => "John"
+donation.last_name  # => "Doe"
+donation.amount  # => BigDecimal("15.0")
+donation.entity  # => Kentaa::Api::Resources::Site
 ```
 
-### Requests
-
-Below a summary of the supported requests per endpoint.
+See also the [Kentaa API docs](https://developer.kentaa.nl/kentaa-api/#donations) and [Kentaa::Api::Resources::Donation](lib/kentaa/api/resources/donation.rb) for all available properties.
 
-#### Actions
+### Manual donations
 
 ```ruby
-actions = client.actions.list             # get actions (paginated)
-actions = client.actions.all              # get all actions (non-paginated)
-
-action = client.actions.get(1)            # query action by ID
-action = client.actions.get("john-doe")   # query action by slug
+# List Manual donations
+donations = client.manual_donations.list  # paginated
+donations = client.manual_donations.all   # non-paginated
+
+donations.each do |donations|
+  donation.first_name  # => "John"
+  donation.last_name  # => "Doe"
+end
+
+# Get Manual donation
+donation = client.manual_donations.get(1)
+
+donation.first_name  # => "John"
+donation.last_name  # => "Doe"
+donation.amount  # => BigDecimal("15.0")
+donation.entity  # => Kentaa::Api::Resources::Site
+
+# Create a Manual donation
+donation = client.manual_donations.create(
+  first_name: "John",
+  last_name: "Doe",
+  amount: "15.0"
+)
+
+donation.id  # => 1
+donation.first_name  # => "John"
+donation.last_name  # => "Doe"
+donation.amount  # => BigDecimal("15.0")
+donation.entity  # => Kentaa::Api::Resources::Site
+
+# Update a Manual donation
+donation = client.manual_donations.update(1, first_name: "Jane")
+
+donation.first_name  # => "Jane"
+
+# Delete a Manual donation
+client.manual_donations.delete(1)
 ```
 
-See also the [Kentaa API docs](https://api.kentaa.nl/v1/doc/actions).
+See also the [Kentaa API docs](https://developer.kentaa.nl/kentaa-api/#manual-donations) and [Kentaa::Api::Resources::ManualDonation](lib/kentaa/api/resources/manual_donation.rb) for all available properties.
 
-#### Donations
+### Newsletter subscriptions
 
 ```ruby
-donations = client.donations.list      # get donations (paginated)
-donations = client.donations.all       # get all donations (non-paginated)
+# List Newsletter subscriptions
+newsletter_subscriptions = client.newsletter_subscriptions.list  # paginated
+newsletter_subscriptions = client.newsletter_subscriptions.all   # non-paginated
+
+newsletter_subscriptions.each do |subscription|
+  subscription.email  # => "john.doe@kentaa.nl"
+  subscription.subscription_url  # => "https://demo1.kentaa.nl"
+end
 
-donation = client.donations.get(1)     # query donation by ID
+# Get Newsletter subscription
+subscription = client.newsletter_subscriptions.get(1)
+
+subscription.email  # => "john.doe@kentaa.nl"
+subscription.subscription_url  # => "https://demo1.kentaa.nl"
 ```
 
-See also the [Kentaa API docs](https://api.kentaa.nl/v1/doc/donations).
+See also the [Kentaa API docs](https://developer.kentaa.nl/kentaa-api/#newsletter-subscriptions) and [Kentaa::Api::Resources::NewsletterSubscription](lib/kentaa/api/resources/newsletter_subscription.rb) for all available properties.
 
-#### Newsletter subscriptions
+### Projects
 
 ```ruby
-newsletter_subscriptions = client.newsletter_subscriptions.list       # get newsletter subscriptions (paginated)
-newsletter_subscriptions = client.newsletter_subscriptions.all        # get all newsletter subscriptions (non-paginated)
+# List Projects
+projects = client.projects.list  # paginated
+projects = client.projects.all   # non-paginated
+
+projects.each do |project|
+  project.title  # => "Dignissimos provident rerum enim alias magni asperna..."
+  project.target_amount  # => 250000
+end
+
+# Get Project by ID or slug
+project = client.projects.get(1)
+project = client.projects.get("project")
+
+project.title  # => "Dignissimos provident rerum enim alias magni asperna..."
+project.target_amount  # => 250000
+project.url  # => "https://demo1.kentaa.nl/project/dignissimos-provident-rerum-enim-alias-magni-asperna"
+```
+
+See also the [Kentaa API docs](https://developer.kentaa.nl/kentaa-api/#projects) and [Kentaa::Api::Resources::Project](lib/kentaa/api/resources/project.rb) for all available properties.
 
+### Recurring donors
 
-newsletter_subscriptions = client.newsletter_subscriptions.get(1)     # query newsletter subscription by ID
+```ruby
+# List Recurring donors
+recurring_donors = client.recurring_donors.list  # paginated
+recurring_donors = client.recurring_donors.all   # non-paginated
+
+recurring_donors.each do |recurring_donor|
+  recurring_donor.first_name  # => "John"
+  recurring_donor.last_name  # => "Doe"
+end
+
+# Get Recurring donor
+recurring_donor = client.recurring_donors.get(1)
+
+recurring_donor.first_name  # => "John"
+recurring_donor.last_name  # => "Doe"
+recurring_donor.amount  # => BigDecimal("15.0")
+recurring_donor.entity  # => Kentaa::Api::Resources::DonationForm
 ```
 
-See also the [Kentaa API docs](https://api.kentaa.nl/v1/doc/newsletter-subscriptions).
+See also the [Kentaa API docs](https://developer.kentaa.nl/kentaa-api/#recurring-donors) and [Kentaa::Api::Resources::RecurringDonor](lib/kentaa/api/resources/recurring_donor.rb) for all available properties.
 
-#### Projects
+### Segments
 
 ```ruby
-projects = client.projects.list            # get projects (paginated)
-projects = client.projects.all             # get all projects (non-paginated)
-
-project = client.projects.get(1)           # query project by ID
-project = client.projects.get("project")   # query project by slug
+# List Segments
+segments = client.segments.list  # paginated
+segments = client.segments.all   # non-paginated
+
+segments.each do |segment|
+  segment.name  # => "Segment 2"
+  segment.url  # => "https://segment-2.demo1.kentaa.nl/"
+end
+
+# Get Segment
+segment = client.segments.get(1)
+
+segment.name  # => "Segment 2"
+segment.title  # => "Aut est maxime nostrum."
+segment.url  # => "https://segment-2.demo1.kentaa.nl/"
+segment.target_amount  # => 2685
 ```
 
-See also the [Kentaa API docs](https://api.kentaa.nl/v1/doc/projects).
+See also the [Kentaa API docs](https://developer.kentaa.nl/kentaa-api/#segments) and [Kentaa::Api::Resources::Segment](lib/kentaa/api/resources/segment.rb) for all available properties.
 
-#### Segments
+### Sites
+
+The only method here is `current`, since there is only one site per API key.
 
 ```ruby
-segments = client.segments.list       # get segments (paginated)
-segments = client.segments.all        # get all segments (non-paginated)
+# Get current Site
+site = client.sites.current
 
-segment = client.segments.get(1)      # query segment by ID
+site.title  # => "Aut est maxime nostrum."
+site.description  # => "Maiores ut velit fugiat eos. Quae est nostrum rerum aut et nihil. Sequi eveniet occaecati et est corporis et enim."
+site.url  # => "https://demo1.kentaa.nl/"
 ```
 
-See also the [Kentaa API docs](https://api.kentaa.nl/v1/doc/segments).
+See also the [Kentaa API docs](https://developer.kentaa.nl/kentaa-api/#sites) and [Kentaa::Api::Resources::Site](lib/kentaa/api/resources/site.rb) for all available properties.
+
+### Teams
+
+```ruby
+# List Teams
+teams = client.teams.list  # paginated
+teams = client.teams.all   # non-paginated
+
+teams.each do |team|
+  team.name  # => "Asperiores beatae voluptate qui."
+  team.url  # => "https://demo1.kentaa.nl/team/asperiores-beatae-voluptate-qui"
+end
+
+# Get Team by ID or slug
+team = client.teams.get(1)
+team = client.teams.get("team")
+
+team.name  # => "Asperiores beatae voluptate qui."
+team.url  # => "https://demo1.kentaa.nl/team/asperiores-beatae-voluptate-qui"
+team.total_amount  # => BigDecimal("225.0")
+```
 
-#### Sites
+See also the [Kentaa API docs](https://developer.kentaa.nl/kentaa-api/#teams) and [Kentaa::Api::Resources::Team](lib/kentaa/api/resources/team.rb) for all available properties.
 
-The only method here is `current`, since there is only one site.
+### Users
 
 ```ruby
-site = client.sites.current    # get the current site
+# List Users
+users = client.users.list  # paginated
+users = client.users.all   # non-paginated
+
+users.each do |user|
+  user.first_name  # => "John"
+  user.last_name  # => "Doe"
+end
+
+# Get User
+user = client.users.get(1)
+
+user.first_name  # => "John"
+user.last_name  # => "Doe"
+
+# Create an User
+user = client.users.create(
+  first_name: "John",
+  last_name: "Doe"
+)
+
+user.id  # => 1
+user.first_name  # => "John"
+user.last_name  # => "Doe"
+
+# Update an User
+user = client.users.update(1, first_name: "Jane")
+
+user.first_name  # => "Jane"
+
+# Authenticate an User
+user = client.users.auth(email: "john.doe@kentaa.nl", password: "secret")
+
+user.id  # => 1
+user.first_name  # => "John"
+user.last_name  # => "Doe"
 ```
 
-See also the [Kentaa API docs](https://api.kentaa.nl/v1/doc/sites).
+See also the [Kentaa API docs](https://developer.kentaa.nl/kentaa-api/#users) and [Kentaa::Api::Resources::User](lib/kentaa/api/resources/user.rb) for all available properties.
+
+### Pagination
 
-#### Teams
+The `list` method on the endpoint returns an [Enumerable](https://ruby-doc.org/core/Enumerable.html) object with paginated results.
+Default page size is 25, but you can can customize this by setting the `per_page` parameter:
 
 ```ruby
-teams = client.teams.list          # get teams (paginated)
-teams = client.teams.all           # get all teams (non-paginated)
+actions = client.actions.list(per_page: 100)
 
-team = client.teams.get(1)         # query team by ID
-team = client.teams.get("team")    # query team by slug
+actions.each do |action|
+  action.title  # => "Lorem ipsum"
+  action.url  # => "https://demo1.kentaa.nl/actie/john-doe"
+end
 ```
 
-See also the [Kentaa API docs](https://api.kentaa.nl/v1/doc/teams).
+You can iterate through the pages using the `.next` method and checking the result:
 
+```ruby
+actions = client.actions.list
+
+loop do  
+  actions.each do |action|
+    # Do something with actions
+  end
+
+  actions = actions.next
+  break if actions.nil?
+end
+```
 
-#### Users
+The `all` method on the endpoint returns a lazy [Enumerator](https://ruby-doc.org/core/Enumerator.html) and will automatically iterate through all pages and retrieve the requested data.
 
 ```ruby
-users = client.users.list          # get users (paginated)
-users = client.users.all           # get all users (non-paginated)
+actions = client.actions.all
 
-user = client.users.get(1)         # query user by ID
+actions.each do |action|
+  action.title  # => "Lorem ipsum"
+  action.url  # => "https://demo1.kentaa.nl/actie/john-doe"
+end
 ```
 
-See also the [Kentaa API docs](https://api.kentaa.nl/v1/doc/users).
+See [Kentaa::Api::Resources::List](lib/kentaa/api/resources/list.rb) for all available pagination methods.
+
+## Error handling
+
+All responses that are not HTTP status 20x will result in a [Kentaa::Api::RequestError](lib/kentaa/api/exception.rb).
 
+```ruby
+begin
+  client.actions.get("invalid")
+rescue Kentaa::Api::RequestError => e
+  e.message  # => "404: Requested resource was not found."
+  e.http_code  # => 404
+  e.errors  # => Array[Kentaa::Api::Resources::Error]
+end
+```
 
 ## Development