reamaze_api 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 95917a571145836ed5a44ce215ef1c1e5ba0e2ae
-  data.tar.gz: 6cf9b15764ba698f2c94294c62ac5e22b8e03a26
+  metadata.gz: fad68d5cd62a6332ad24030733db0643e2307ceb
+  data.tar.gz: eb3694f56e5124e5d364fc9e9b36ef08b4b1a3e2
 SHA512:
-  metadata.gz: e308a9c6d214a96bbb21a3c03384da0e87c595c4e259873f61dba9c1fcc22223af91b4f31caddfad8bd1705a685ca460e4915f84fc983a2ad5c8dff6a3d049d3
-  data.tar.gz: 21db9b12a5a93fc75e7697f125a9773ae8137da624e783a1a21f269e70e772f726bd751cae840457a3043d81014980fc8034d5e5f5c5e189b931bcfc5f37cc2f
+  metadata.gz: 71a5d2f92737fcfbcfb9ebb6921f2ced6952c033527c0316420e377e2effab29a71ab7154d0bc86a15fe3c80e61807aab7573c7127e71d11b5ec29f4c53526f2
+  data.tar.gz: 617e7775821955deb3cc6b87c6fa722820032912ec296d3feb3b89e1974b922911824a61c84bd9197bfb176d4d4b1a11aec2e553f88ec7b243784b89663c42cd

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2016 Joshua Priddle <jpriddle@me.com>
+
+Permission  is  hereby granted, free of charge, to any person ob-
+taining a copy of  this  software  and  associated  documentation
+files  (the "Software"), to deal in the Software without restric-
+tion, including without limitation the rights to use, copy, modi-
+fy, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is  fur-
+nished to do so, subject to the following conditions:
+
+The  above  copyright  notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF  ANY  KIND,
+EXPRESS  OR  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE  AND  NONIN-
+FRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER  IN  AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN  THE
+SOFTWARE.

data/README.md

@@ -66,6 +66,37 @@ client.messages.all
 client.messages.create
 ```
 
+## Pagination
+
+Reamaze paginates responses that return multiple resources (ie: this library's
+`#all` methods), and by default you receive page 1. You can control which page
+to fetch by passing the `:page` parameter:
+
+```ruby
+page1 = client.messages.all
+page2 = client.messages.all(page: 2)
+page3 = client.messages.all(page: 3)
+```
+
+## Auto-Pagination
+
+Auto-pagination allows you to fetch _all_ results without having to manually
+fetch each page. For example, with 3 pages of 30 conversations the following
+would fetch all 90:
+
+```ruby
+conversations = client.conversations.all(auto_paginate: true)
+```
+
+**Beware of API rate limiting!** If you attempt to auto-paginate with a large
+number of pages you may be rate limited by Reamaze. Make sure to apply filters
+where necessary (eg: `all(auto_paginate: true, for: "me@example.com")`).
+
+**Errors** If fetching any page is not successful the error will be returned
+and no further pages will be fetched.
+
+## Customization and Middleware
+
 ReamazeAPI uses the [Faraday][] library for HTTP interactions, and by default,
 Net::HTTP. To configure a different HTTP adapter you can set
 `Faraday.default_adapter`:
@@ -141,3 +172,26 @@ push git commits and tags, and push the `.gem` file to
 Bug reports and pull requests are welcome on GitHub at
 https://github.com/itspriddle/reamaze_api.
 
+## License
+
+Released under the MIT license:
+
+Copyright (c) 2016 Joshua Priddle <jpriddle@me.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/reamaze_api/article.rb

@@ -14,8 +14,9 @@ module ReamazeAPI
     # Returns a Hash.
     def all(params = {})
       params = Utils.symbolize_hash(params)
+      url    = articles_path(params.delete(:topic))
 
-      get articles_path(params.delete(:topic)), params
+      paginate url, :articles, params
     end
 
     # Public: Retrieves a specific KB article.

data/lib/reamaze_api/channel.rb

@@ -12,7 +12,7 @@ module ReamazeAPI
     #
     # Returns a Hash.
     def all(params = {})
-      get "/channels", params
+      paginate "/channels", :channels, params
     end
 
     # Public: Retrieve a specific channel.

data/lib/reamaze_api/client.rb

@@ -37,9 +37,9 @@ module ReamazeAPI
 
     # Public: Initialize a new Client instance.
     #
-    # brand: Brand name (subdomain from your Reamaze URL)
-    # login: Reamaze login
-    # token: Reamaze API token
+    # brand - Brand name (subdomain from your Reamaze URL)
+    # login - Reamaze login
+    # token - Reamaze API token
     #
     # Yields a Faraday::Connection if a block is given.
     #
@@ -98,9 +98,9 @@ module ReamazeAPI
 
     # Private: Submits an HTTP request to the upstream API.
     #
-    # method: HTTP method (eg: :get, :post)
-    # path:   API path (without `/api/v1` prefix, eg: "/messages")
-    # params: Hash of parameters to send with the request (default: {})
+    # method - HTTP method (eg: :get, :post)
+    # path   - API path (without `/api/v1` prefix, eg: "/messages")
+    # params - Hash of parameters to send with the request (default: {})
     #
     # Raises a ReamazeAPI::Error for any HTTP response code 400-599 unless
     # `ReamazeAPI.config.exceptions` is false.
@@ -118,11 +118,50 @@ module ReamazeAPI
       Utils.error_hash(e)
     end
 
+    # Private: Performs a GET request on the given path/resource. If results
+    # are more than one page, each additional page is fetched and added to the
+    # payload. If any page returns an error response, that response is
+    # immediately returned and no further requests are performed.
+    #
+    # NOTE: Beware of API rate limiting when using this method with large
+    # datasets.
+    #
+    # path     - API path (without `/api/v1` prefix, eg: "/messages")
+    # resource - ReamazeAPI resource name (eg: `:messages`)
+    # params   - Hash of parameters to send with the request (default: {})
+    #
+    # Returns a Hash.
+    def paginate(path, resource, params = {})
+      params        = Utils.symbolize_hash(params)
+      auto_paginate = params.delete(:auto_paginate)
+      output        = get(path, params)
+      page          = params.fetch(:page, 1)
+      success       = output[:success]
+      payload       = output[:payload]
+      page_count    = payload[:page_count]
+
+      if success && auto_paginate && page_count && page_count > page
+        more = paginate(path, resource, params.merge(
+          page:          page.next,
+          auto_paginate: true
+        ))
+
+        if more[:success] && more[:payload]
+          payload[resource].concat more[:payload][resource]
+        else
+          output[:success] = false
+          output[:payload] = more[:payload]
+        end
+      end
+
+      output
+    end
+
     # Private: `get`, `put`, and `post` helper methods. These submit an HTTP
     # request to the upstream API.
     #
-    # path:   API path (without `/api/v1` prefix, eg: "/messages")
-    # params: Hash of parameters to send with the request (default: {})
+    # path   - API path (without `/api/v1` prefix, eg: "/messages")
+    # params - Hash of parameters to send with the request (default: {})
     #
     # Returns a Hash.
     HTTP_METHODS.each do |method|

data/lib/reamaze_api/contact.rb

@@ -12,7 +12,7 @@ module ReamazeAPI
     #
     # Returns a Hash.
     def all(params = {})
-      get "/contacts", params
+      paginate "/contacts", :contacts, params
     end
 
     # Public: Create a new contact.

data/lib/reamaze_api/conversation.rb

@@ -12,7 +12,7 @@ module ReamazeAPI
     #
     # Returns a Hash.
     def all(params = {})
-      get "/conversations", params
+      paginate "/conversations", :conversations, params
     end
 
     # Public: Retrieve a specific conversation.

data/lib/reamaze_api/message.rb

@@ -16,8 +16,9 @@ module ReamazeAPI
     # Returns a Hash.
     def all(params = {})
       params = Utils.symbolize_hash(params)
+      url    = message_path(params.delete(:conversation_slug))
 
-      get message_path(params.delete(:conversation_slug)), params
+      paginate url, :messages, params
     end
 
     # Public: Create a new message under the given conversation.

data/lib/reamaze_api/resource.rb

@@ -5,7 +5,7 @@ module ReamazeAPI
     extend Forwardable
 
     # Delegate HTTP actions back to the given Client.
-    def_delegators :@client, *Client::HTTP_METHODS
+    def_delegators :@client, :paginate, *Client::HTTP_METHODS
 
     # Public: Initialize a new Resource instance. API resources should inherit
     # from this class.

data/lib/reamaze_api/version.rb

@@ -1,3 +1,3 @@
 module ReamazeAPI
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

data/reamaze_api.gemspec

@@ -5,6 +5,7 @@ Gem::Specification.new do |spec|
   spec.version       = ReamazeAPI::VERSION
   spec.authors       = ["Joshua Priddle"]
   spec.email         = ["jpriddle@me.com"]
+  spec.license       = "MIT"
 
   spec.summary       = %q{Reamaze API client}
   spec.description   = %q{Reamaze API client}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reamaze_api
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Joshua Priddle
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-07-14 00:00:00.000000000 Z
+date: 2016-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -104,6 +104,7 @@ files:
 - ".gitignore"
 - ".travis.yml"
 - Gemfile
+- LICENSE
 - README.md
 - Rakefile
 - bin/console
@@ -122,7 +123,8 @@ files:
 - lib/reamaze_api/version.rb
 - reamaze_api.gemspec
 homepage: https://github.com/itspriddle/reamaze_api
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -145,4 +147,3 @@ signing_key:
 specification_version: 4
 summary: Reamaze API client
 test_files: []
-has_rdoc: