makeleaps-ruby 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 197f77977864602aa6998870839d8b46802af2a1283894c61bdc8ffb1a67b12f
-  data.tar.gz: dd6d57e4176c9fc5b0598f7fe571c9996ae63809bf88b07bfe663154ac0814dc
+  metadata.gz: 4660d3c49dd4f6c72b502a5f407ef51735878871dcc993b6fa48d853abc4210b
+  data.tar.gz: f38d04e5c5878aa7149ba81a33fe40083516f751cc80e59eadb6bf91c73793f2
 SHA512:
-  metadata.gz: d4c6d791a94edaa44e903b763e7414eef73497cec011e2002305695b8a6e96c137910414182fa738d7b8294b307418f37e60ddc508e1c9ca2ede29ed1865205c
-  data.tar.gz: 5592b35fe4ad502f60890e12e341edc0a3fac41148b6d372dd6366b13090cfff422733749197c582c7b68f1205438bc0bb1f3c92909977cd1b8dc40a4dce1656
+  metadata.gz: e222e2a49796f5c6bfed46d6c5ee2e3b357d3536e8a1c71ab964490db730c0878689328dd58c921b681a48e88dc9dbc8873da903961eb2ec4a338da936001ce1
+  data.tar.gz: 3266c18b2ce9187be95966f01078995a7ee910f1981ce6e1d339b4990ca934fe41631522fe1a81e52a55de8933cbcea5553701d5bac158511e9877fa6feeb196

data/README.md

@@ -59,6 +59,21 @@ client.get :document, yyyyy                                                 # en
 client.get :document # fetching a list of documents
 client.get :contact  # fetching a list of contacts
 
+# adding a query
+documents = client.get :document { |req| req.params['document_number'] = "1000" }
+documents = client.get :document { |req| req.params['date__lt'] = "2020-01-30" }
+```
+
+#### Traversal access
+When you want to retrieve a collection of resources (e.g. invoices, cliet contacts..) which size is larger than that a single response can contain, you need to make a consecutive chain of calls, following the `next` link provided by the prior response.
+
+To traverse multiple pages following `next` links, below methods such as `#each_page`, `#each_resource`, `#find_resource` are available for convenience.
+
+WARNING: this could potentially invoke an unexpected number of API calls. Consider limiting your possibile accesses, otherwise you might exceed the maximum allowed number of requests (see [throttling](https://app.makeleaps.com/api/docs/) in the API document)
+
+Current default limit is set as 100 pages / each method, and the rate limit is set as 0.1sec / request so that it won't cause accidental traffic to the API.
+
+```ruby
 # visiting all pages (following `next` links provided by API)
 # (requests are limited at maximum rate of 0.1sec per each)
 total_count = 0
@@ -66,8 +81,25 @@ client.each_page :document do |documents|
   total_count += documents.count
 end
 
+# query strings can be added with `params` option
+# this will invoke
+# GET 'https://api.makeleaps.com/api/partner/<partner_id>/document/?document_type=invoice&&date__gte=2019-01-01&&date__lt=2019-04-01'
+# and follows `next` url until it reaches to the last page OR the maximum limit page (default 100)
+total_count = 0
+client.each_page :document, params: {document_type: :invoice, date__gte: '2019-01-01', date__lt: '2019-04-01'} do |documents|
+  total_count += documents.count
+end
+
+# each resources (that each page contains) can also be accessed via #each_resource
+# (interface are consistent with #each_page)
+client.each_resouce :document, params: {document_type: :invoice, date__gte: '2019-01-01', date__lt: '2019-04-01'} do |invoice|
+  puts invoice['display_name']
+end
+
 # find a resource (out of all the pages)
-client.find_resource(:document) do |document|
+# visits next_urls one after another. terminates when it find the first resource (with whivh the given block evaluates as true), or when it reaches to one of either the last page OR the max page (default 100)
+# returns the detected resource or nil (when not found)
+client.find_resource(:document), params: {document_type: :invoice} do |document|
   document['title'].match? /URGENT/
 end
 
@@ -76,10 +108,6 @@ documents = client.get :document
 document.find_resource do |document|
   document['document_number'].to_i >= 123 && document['note'].match? /IMPORTANT/
 end
-
-# adding a query
-documents = client.get :document { |req| req.params['document_number'] = "1000" }
-documents = client.get :document { |req| req.params['date__lt'] = "2020-01-30" }
 ```
 
 #### POST/PATCH/PUT/DELETE

data/lib/makeleaps/client.rb

@@ -10,18 +10,20 @@ module Makeleaps
     attr_reader    :request
     def_delegators :@request, :get, :post, :put, :patch, :delete, :options
     def_delegators :@request, :each_page, :each_resource, :find_resource, :set_partner!
+    def_delegators :@request, :connection
 
     def initialize(username, password)
-      @auth = Makeleaps::Request::BasicAuth.new(username, password)
+      @auth_request = Makeleaps::Request::BasicAuth.new(username, password)
     end
 
     def connect!
-      token_store = @auth.make_request!
-      @request = Makeleaps::Request::Generic.new(token_store.access_token)
+      @token_store ||= @auth_request.authenticate!
+      @request = Makeleaps::Request::Generic.new(@token_store.access_token) if @token_store.valid?
     end
 
-    def connection
-      request.connection
+    def disconnect!
+      @auth_request.revoke!(@token_store.access_token) if @token_store&.valid?
+      @token_store = nil
     end
   end
 end

data/lib/makeleaps/request/basic_auth.rb

@@ -5,7 +5,8 @@ module Makeleaps
     class BasicAuth < Base
       include ErrorHandler
 
-      AUTH_ENDPOINT = 'user/oauth2/token/'
+      AUTH_ENDPOINT       = 'user/oauth2/token/'
+      REVOCATKON_ENDPOINT = 'user/oauth2/revoke-token/'
 
       def initialize(username, password)
         super() do |conn|
@@ -13,12 +14,18 @@ module Makeleaps
         end
       end
 
-      def make_request!
+      def authenticate!
         response = handle_api_response do
-          connection.post(AUTH_ENDPOINT) { |req| req.params['grant_type'] = 'client_credentials'}
+          connection.post(AUTH_ENDPOINT) { |req| req.params['grant_type'] = 'client_credentials' }
         end
         Makeleaps::Response::TokenStore.new response
       end
+
+      def revoke!(token)
+        handle_api_response do
+          connection.post(REVOCATKON_ENDPOINT) { |req| req.params['token'] = token }
+        end
+      end
     end
   end
 end

data/lib/makeleaps/request/generic.rb

@@ -27,12 +27,16 @@ module Makeleaps
         partners.find_resource { |partner| partner['name'] == name }
       end
 
-      # process sequentially (avoid eager loading) to ensure minimum API access
-      def each_page(start_page , &block)
+      # set max_pages to change the maximum number of retrievable pages 
+      # WARNING: this might invoke too many API accesses.
+      def each_page(start_page, *args, params: nil, max_pages: nil, &block)
         next_url = start_page
+        max_pages = max_pages || 100 # TODO: let default value be customizeable using config
 
-        loop do
-          response = get(next_url)
+        max_pages.times do
+          response = get(next_url, *args) { |req|
+            req.params.merge!(params) unless params.nil?
+          }
           block.call(response)
           next_url = response.next
           break unless next_url
@@ -40,16 +44,18 @@ module Makeleaps
         end
       end
 
-      def each_resource(start_page , &block)
-        each_page(start_page) do |page|
+      # set max_pages to change the maximum number of retrievable pages 
+      # WARNING: this might invoke too many API accesses.
+      def each_resource(start_page, *args, params: nil, max_pages: nil, &block)
+        each_page(start_page, *args, params: params, max_pages: max_pages) do |page|
           page.each_resource do |resource|
             block.call(resource)
           end
         end
       end
 
-      def find_resource(start_page, *args, &block)
-        each_page(start_page) do |page|
+      def find_resource(start_page, *args, params: nil, max_pages: nil, &block)
+        each_page(start_page, params: params, max_pages: max_pages) do |page|
           resource = page.find_resource(*args, &block)
           return resource if resource
         end

data/lib/makeleaps/response/access_token.rb

@@ -14,10 +14,12 @@ module Makeleaps
         @access_token ||= body['access_token']
       end
 
-      def valid_request?
+      def valid?
         response && response.status == 200 && !expired?
       end
 
+    private
+
       def expired?
         Time.now >= requested_at + expiration_period
       end

data/lib/makeleaps/version.rb

@@ -1,3 +1,3 @@
 module Makeleaps
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: makeleaps-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Koji Onishi
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-06-21 00:00:00.000000000 Z
+date: 2019-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday