pco_api 1.1.2 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d2a0b33bcc7a92d15c4bc6aac5fb0056c6d06aeb
-  data.tar.gz: d679b3d3923bba077c046e80b273a6f72a82ab74
+SHA256:
+  metadata.gz: eee1d9d3e7b4407dfc0b5f183021246c34a1467936fb77743c4cd45a1767b9b7
+  data.tar.gz: 014ec30ad0b2c1b814b10da5ee26716f55cea5bf85a782e4230feaadf7f0c260
 SHA512:
-  metadata.gz: 2b814cf14e00f50caecb6676e1064bfe2e218b8dc46ea41e495a67edf1a5ad2daf2bb693c54afbbbbd74301c415bf5509e450d394f743729a731c90ed2226a5e
-  data.tar.gz: 305313b12a741a953a3f82f945e07dffcc70c3b86395212227b7d3a5046f6e6f33bca80815f5e994e3ea236022fdf64579cdb654670534c49cdcbf8fc3c63b2a
+  metadata.gz: b36cca693f502f4c4b123aa22c61b72d41ccd51457eee7c2aef87454559d1fb7ffe85241ec97ab8832925830f864e773ce22b319d278f474245826f44bfe20e1
+  data.tar.gz: 3c16320118da5aee58fcec347cae41df8c215d176331863d61d079a0b47bbc23998816ff09dbecbce888177faa7847da2f13f66fe4c984622fb74cb641eb9372

data/README.md

@@ -42,6 +42,13 @@ gem install pco_api
     # GET /people/v2/households?order=name
     ```
 
+5. To query dataset according to `can_query_by` variables:
+
+    ```ruby
+    api.people.v2.people.get('where[membership]': 'Member')
+    # GET /people/v2/people?where[membership]=Member
+    ```
+
 ## Example
 
 ```ruby
@@ -63,22 +70,24 @@ api.people.v2.people.get(order: 'last_name')
     {
       "type" => "Person",
       "id" => "271",
-      "first_name" => "Jean",
-      "middle_name" => nil,
-      "last_name" => "Abernathy",
-      "birthdate" => "1885-01-01",
-      "anniversary" => nil,
-      "gender" => "F",
-      "grade" => -1,
-      "child" => false,
-      "status" => "active",
-      "school_type" => nil,
-      "graduation_year" => nil,
-      "site_administrator" => false,
-      "people_permissions" => nil,
-      "created_at" => "2015-04-01T20:18:22Z",
-      "updated_at" => "2015-04-10T18:59:51Z",
-      "avatar" => nil,
+      "attributes" => {
+        "first_name" => "Jean",
+        "middle_name" => nil,
+        "last_name" => "Abernathy",
+        "birthdate" => "1885-01-01",
+        "anniversary" => nil,
+        "gender" => "F",
+        "grade" => -1,
+        "child" => false,
+        "status" => "active",
+        "school_type" => nil,
+        "graduation_year" => nil,
+        "site_administrator" => false,
+        "people_permissions" => nil,
+        "created_at" => "2015-04-01T20:18:22Z",
+        "updated_at" => "2015-04-10T18:59:51Z",
+        "avatar" => nil,
+      },
       "links" => {
         "self" => "https://api.planningcenteronline.com/people/v2/people/271"
       }
@@ -91,7 +100,7 @@ api.people.v2.people.get(order: 'last_name')
     "next" => {
       "offset" => 25
     },
-    "orderable_by" => [
+    "can_order_by" => [
       "first_name",
       "middle_name",
       "last_name",
@@ -108,7 +117,7 @@ api.people.v2.people.get(order: 'last_name')
       "created_at",
       "updated_at"
     ],
-    "filterable_by" => [
+    "can_query_by" => [
       "first_name",
       "middle_name",
       "last_name",
@@ -137,7 +146,11 @@ api.people.v2.people.get(order: 'last_name')
       "name_suffix",
       "field_data",
       "apps"
-    ]
+    ],
+    "parent" => {
+      "id" => "1",
+      "type" => "Organization"
+    }
   }
 }
 ```
@@ -197,22 +210,27 @@ The following errors may be raised by the library, depending on the API response
 | 404                 | `PCO::API::Errors::NotFound` < `PCO::API::Errors::ClientError`            |
 | 405                 | `PCO::API::Errors::MethodNotAllowed` < `PCO::API::Errors::ClientError`    |
 | 422                 | `PCO::API::Errors::UnprocessableEntity` < `PCO::API::Errors::ClientError` |
+| 429                 | `PCO::API::Errors::TooManyRequests` < `PCO::API::Errors::ClientError`     |
 | other 4xx errors    | `PCO::API::Errors::ClientError`                                           |
 | 500                 | `PCO::API::Errors::InternalServerError` < `PCO::API::Errors::ServerError` |
 | other 5xx errors    | `PCO::API::Errors::ServerError`                                           |
 
 The exception object has the following methods:
 
-| Method  | Content                                 |
-| ------- | --------------------------------------- |
-| status  | HTTP status code returned by the server |
-| message | the message returned by the API         |
+| Method  | Content                                     |
+| ------- | ------------------------------------------- |
+| status  | HTTP status code returned by the server     |
+| message | the message returned by the API             |
+| detail  | the full error response returned by the API |
+| headers | hash of HTTP headers returned by the API    |
 
 The `message` should be a simple string given by the API, e.g. "Resource Not Found".
 
+In the case of validation errors, the `message` is a summary string built from the raw `detail`.
+
 Alternatively, you may rescue `PCO::API::Errors::BaseError` and branch your code based on
 the status code returned by calling `error.status`.
 
 ## Copyright & License
 
-Copyright 2015, Ministry Centered Technologies. Licensed MIT.
+Copyright Ministry Centered Technologies. Licensed MIT.

data/lib/pco/api.rb

@@ -4,8 +4,8 @@ require_relative 'api/errors'
 module PCO
   module API
     module_function
-    def new(*args)
-      Endpoint.new(*args)
+    def new(**args)
+      Endpoint.new(**args)
     end
   end
 end

data/lib/pco/api/endpoint.rb

@@ -5,6 +5,10 @@ module PCO
   module API
     URL = 'https://api.planningcenteronline.com'
 
+    class Response < Hash
+      attr_accessor :headers
+    end
+
     class Endpoint
       attr_reader :url, :last_result
 
@@ -69,7 +73,9 @@ module PCO
       def _build_response(result)
         case result.status
         when 200..299
-          result.body
+          res = Response[result.body]
+          res.headers = result.headers
+          res
         when 400
           fail Errors::BadRequest, result
         when 401
@@ -82,6 +88,8 @@ module PCO
           fail Errors::MethodNotAllowed, result
         when 422
           fail Errors::UnprocessableEntity, result
+        when 429
+          fail Errors::TooManyRequests, result
         when 400..499
           fail Errors::ClientError, result
         when 500
@@ -116,7 +124,6 @@ module PCO
 
       def _build_connection
         Faraday.new(url: url) do |faraday|
-          faraday.adapter :excon
           faraday.response :json, content_type: /\bjson$/
           if @basic_auth_token && @basic_auth_secret
             faraday.basic_auth @basic_auth_token, @basic_auth_secret
@@ -125,6 +132,7 @@ module PCO
           else
             fail Errors::AuthRequiredError, "You must specify either HTTP basic auth credentials or an OAuth2 access token."
           end
+          faraday.adapter :excon
         end
       end
     end

data/lib/pco/api/errors.rb

@@ -4,32 +4,59 @@ module PCO
       class AuthRequiredError < StandardError; end
 
       class BaseError < StandardError
-        attr_reader :status
+        attr_reader :status, :detail, :headers
 
         def initialize(response)
           @status = response.status
-          @message = response.body.is_a?(Hash) && response.body['message'] || response.body.to_s
+          @detail = response.body
+          @headers = response.headers
         end
 
         def to_s
-          @message
+          message
+        end
+
+        def message
+          return detail.to_s unless detail.is_a?(Hash)
+          detail['message'] || validation_message || detail.to_s
         end
 
         def inspect
-          "<#{self.class.name} status=#{@status} message=#{@message}>"
+          "<#{self.class.name} status=#{status} message=#{message.inspect} detail=#{detail.inspect}>"
+        end
+
+        private
+
+        def validation_message
+          return if Array(detail['errors']).empty?
+          errors = detail['errors'].map do |error|
+            error_to_string(error)
+          end
+          errors.uniq.join('; ')
+        end
+
+        def error_to_string(error)
+          return unless error.is_a?(Hash)
+          [
+            "#{error['title']}:",
+            error.fetch('meta', {})['resource'],
+            error.fetch('source', {})['parameter'],
+            error['detail']
+          ].compact.join(' ')
         end
       end
 
-      class ClientError              < BaseError;   end # 400..499
-      class BadRequest               < ClientError; end # 400
-      class Unauthorized             < ClientError; end # 401
-      class Forbidden                < ClientError; end # 403
-      class NotFound                 < ClientError; end # 404
-      class MethodNotAllowed         < ClientError; end # 405
-      class UnprocessableEntity      < ClientError; end # 422
+      class ClientError         < BaseError;   end # 400..499
+      class BadRequest          < ClientError; end # 400
+      class Unauthorized        < ClientError; end # 401
+      class Forbidden           < ClientError; end # 403
+      class NotFound            < ClientError; end # 404
+      class MethodNotAllowed    < ClientError; end # 405
+      class UnprocessableEntity < ClientError; end # 422
+      class TooManyRequests     < ClientError; end # 429
 
-      class ServerError              < BaseError;   end # 500..599
-      class InternalServerError      < ServerError; end # 500
+      class ServerError         < BaseError;   end # 500..599
+      class InternalServerError < ServerError; end # 500
     end
   end
 end

data/lib/pco/api/version.rb

@@ -1,5 +1,5 @@
 module PCO
   module API
-    VERSION = '1.1.2'
+    VERSION = '1.3.1'
   end
 end

data/spec/pco/api/endpoint_spec.rb

@@ -50,6 +50,7 @@ describe PCO::API::Endpoint do
       it 'returns the result of making a GET request to the endpoint' do
         expect(@result).to be_a(Hash)
         expect(@result['data']).to eq(result)
+        expect(@result.headers).to eq('Content-Type' => 'application/vnd.api+json')
       end
     end
 
@@ -76,6 +77,7 @@ describe PCO::API::Endpoint do
                 end
         expect(error.status).to eq(404)
         expect(error.message).to eq('Resource Not Found')
+        expect(error.headers).to eq('Content-Type' => 'application/vnd.api+json')
       end
     end
 

data/spec/pco/api_spec.rb

@@ -0,0 +1,9 @@
+require_relative '../spec_helper'
+
+describe PCO::API do
+  describe '.new' do
+    it 'creates a new Endpoint instance' do
+      expect(described_class.new(basic_auth_token: 'abc123', basic_auth_secret: 'xyz789').class).to eq(PCO::API::Endpoint)
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pco_api
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.3.1
 platform: ruby
 authors:
 - Planning Center Online
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-08 00:00:00.000000000 Z
+date: 2021-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -16,42 +16,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.1
+        version: '0.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.1
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: faraday_middleware
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.1
+        version: '0.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.1
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: excon
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.45.3
+        version: 0.71.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.45.3
+        version: 0.71.0
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -109,6 +109,7 @@ files:
 - lib/pco/api/version.rb
 - lib/pco_api.rb
 - spec/pco/api/endpoint_spec.rb
+- spec/pco/api_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/planningcenter/pco_api_ruby
 licenses:
@@ -129,11 +130,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.4.6
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: API wrapper for api.planningcenteronline.com
 test_files:
+- spec/pco/api_spec.rb
 - spec/pco/api/endpoint_spec.rb
 - spec/spec_helper.rb