atrium-ruby 0.5.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 245392ec9efa63cc44d3d292397c47a32a03a16b
-  data.tar.gz: 4a07efc49acf876f734942c70b9f2e0fb6cd62d5
+  metadata.gz: 938771555b9c5477b1eb655e1296636cf3df04c4
+  data.tar.gz: 19370f5a2dbb896cf12a026c65033169a2d5d767
 SHA512:
-  metadata.gz: a3a18069855ba1a1b7b5076d5428fc856729b1a90a47ac9eab4478ef248922683193317ddce8956602895adb466e4912500dcbd8e02a4fce25ab639fab73fea1
-  data.tar.gz: 3073ba5011c23cf91cd44041d660cf258a29ccb2857f677e57841cd880d7cc01e0fee1896db94b689807fc2a18b86640d263626e58cb438c724d0c7bfbd8d1a4
+  metadata.gz: 06ff6b39928d2c63450e4e5d3f0dcf14490140a018b4452561bdf4e5f3b2ae9972a5bc1813d05d6ea26f7f9244a317e1316b5b48f40c1b35b74488efa0f31f30
+  data.tar.gz: e0444f11d6993852243ee8fc6f0b975d75d03673b94cdb765133543d63d6d5052af53e986a3998292c18416da634402ff12ef39c47de4ae15537db9df52ffc10

data/.rubocop.yml

@@ -6,5 +6,7 @@ AllCops:
   Include:
     - 'Gemfile'
     - 'Rakefile'
+Style/FileName:
+  Enabled: false
 Style/FrozenStringLiteralComment:
-  Enabled: false
+  Enabled: false

data/README.md

@@ -11,6 +11,58 @@ end
 
 From there, you can start using some basic class methods to make calls for data. See our [full documentation](https://atrium.mx.com/documentation) for more details.
 
+## Examples
+
+### Pagination
+
+The following demonstrates how you can read data back from the API in a memory efficient way using built-in pagination
+helpers. You can also specify query parameters such as `from_date` and `to_date`.
+
+```ruby
+::Atrium::User.list_each do |user|
+  user.each_member do |member|
+    puts member.name
+    puts member.accounts.total_entries
+
+    member.each_account do |account|
+      puts account.name
+      puts account.transactions.total_entries
+
+      account.each_transaction do |transaction|
+        puts transaction.description
+      end
+    end
+  end
+
+  user.each_account do |account|
+    puts account.name
+    puts account.transactions.total_entries
+
+    account.each_transaction do |transaction|
+      puts transaction.description
+    end
+  end
+
+  user.each_transaction do |transaction|
+    puts transaction.description
+  end
+end
+```
+
+### Date Range
+
+You can specify `from_date` and `to_date` to limit or widen your search. For example:
+
+```ruby
+from_date = ::Date.new(2017, 02, 18)
+to_date = ::Date.new(2017, 03, 18)
+params = {:from_date => from_date, :to_date => to_date}
+
+::Atrium::Transaction.list_each(:user_guid => "USR-123", :query_params => params) do |transaction|
+  puts transaction.description
+end
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/atrium.rb

@@ -1,6 +1,7 @@
 require "active_attr"
 require "httpclient"
 require "json"
+require "atrium/pageable"
 require "atrium/paginate"
 
 require "atrium/account"

data/lib/atrium/account.rb

@@ -1,5 +1,6 @@
 module Atrium
   class Account
+    extend ::Atrium::Pageable
     include ::ActiveAttr::Model
 
     # ATTRIBUTES
@@ -32,13 +33,19 @@ module Atrium
     attribute :updated_at
     attribute :user_guid
 
-    def self.list(user_guid:)
-      endpoint = "/users/#{user_guid}/accounts"
-      accounts_response = ::Atrium.client.make_request(:get, endpoint)
+    def self.list(options = {})
+      options = _account_pagination_options(options)
+      paginate(options)
+    end
+
+    def self.list_each(options = {})
+      options = _account_pagination_options(options)
+      paginate_each(options) { |account| yield account }
+    end
 
-      accounts_response["accounts"].map do |account|
-        ::Atrium::Account.new(account)
-      end
+    def self.list_in_batches(options = {})
+      options = _account_pagination_options(options)
+      paginate_in_batches(options) { |batch| yield batch }
     end
 
     def self.read(user_guid:, account_guid:)
@@ -49,13 +56,32 @@ module Atrium
       ::Atrium::Account.new(account_params)
     end
 
-    def transactions
-      endpoint = "/users/#{user_guid}/accounts/#{guid}/transactions"
-      account_transactions_response = ::Atrium.client.make_request(:get, endpoint)
+    def transactions(options = {})
+      options = _transaction_pagination_options(options)
+      self.class.paginate(options)
+    end
+
+    def each_transaction(options = {})
+      options = _transaction_pagination_options(options)
+      self.class.paginate_each(options) { |account| yield account }
+    end
 
-      account_transactions_response["transactions"].map do |transaction|
-        ::Atrium::Transaction.new(transaction)
-      end
+    def transactions_in_batches(options = {})
+      options = _transaction_pagination_options(options)
+      self.class.paginate_in_batches(options) { |batch| yield batch }
+    end
+
+    def self._account_pagination_options(options)
+      user_guid = options.fetch(:user_guid)
+      endpoint = "/users/#{user_guid}/accounts"
+      options.merge(:endpoint => endpoint, :resource => "accounts")
+    end
+
+  private
+
+    def _transaction_pagination_options(options)
+      endpoint = "/users/#{user_guid}/accounts/#{guid}/transactions"
+      options.merge(:endpoint => endpoint, :resource => "transactions", :klass => ::Atrium::Transaction)
     end
   end
 end

data/lib/atrium/member.rb

@@ -1,7 +1,7 @@
 module Atrium
   class Member
+    extend ::Atrium::Pageable
     include ::ActiveAttr::Model
-    include ::ActiveAttr::Attributes
 
     attribute :aggregated_at
     attribute :guid
@@ -25,13 +25,19 @@ module Atrium
       ::Atrium::Member.new(member_params)
     end
 
-    def self.list(user_guid:)
-      endpoint = "/users/#{user_guid}/members"
-      members_response = ::Atrium.client.make_request(:get, endpoint)
+    def self.list(options = {})
+      options = _member_pagination_options(options)
+      paginate(options)
+    end
 
-      members_response["members"].map do |member|
-        ::Atrium::Member.new(member)
-      end
+    def self.list_each(options = {})
+      options = _member_pagination_options(options)
+      paginate_each(options) { |member| yield member }
+    end
+
+    def self.list_in_batches(options = {})
+      options = _member_pagination_options(options)
+      paginate_in_batches(options) { |batch| yield batch }
     end
 
     def self.read(user_guid:, member_guid:)
@@ -45,13 +51,19 @@ module Atrium
     ##
     # INSTANCE METHODS
     #
-    def accounts
-      endpoint = "/users/#{user_guid}/members/#{guid}/accounts"
-      accounts_response = ::Atrium.client.make_request(:get, endpoint)
+    def accounts(options = {})
+      options = _account_pagination_options(options)
+      self.class.paginate(options)
+    end
 
-      accounts_response["accounts"].map do |account|
-        ::Atrium::Account.new(account)
-      end
+    def each_account(options = {})
+      options = _account_pagination_options(options)
+      self.class.paginate_each(options) { |account| yield account }
+    end
+
+    def accounts_in_batches(options = {})
+      options = _account_pagination_options(options)
+      self.class.paginate_in_batches(options) { |batch| yield batch }
     end
 
     def aggregate
@@ -120,13 +132,25 @@ module Atrium
       self
     end
 
-    def transactions
-      endpoint = "/users/#{user_guid}/members/#{guid}/transactions"
-      transactions_response = ::Atrium.client.make_request(:get, endpoint)
+    def transactions(options = {})
+      options = _transaction_pagination_options(options)
+      self.class.paginate(options)
+    end
 
-      transactions_response["transactions"].map do |transaction|
-        ::Atrium::Transaction.new(transaction)
-      end
+    def each_transaction(options = {})
+      options = _transaction_pagination_options(options)
+      self.class.paginate_each(options) { |transaction| yield transaction }
+    end
+
+    def transactions_in_batches(options = {})
+      options = _transaction_pagination_options(options)
+      self.class.paginate_in_batches(options) { |batch| yield batch }
+    end
+
+    def self._member_pagination_options(options)
+      user_guid = options.fetch(:user_guid)
+      endpoint = "/users/#{user_guid}/members"
+      options.merge(:endpoint => endpoint, :resource => "members")
     end
 
     ##
@@ -147,6 +171,11 @@ module Atrium
     ##
     # PRIVATE INSTANCE METHODS
     #
+    def _account_pagination_options(options)
+      endpoint = "/users/#{user_guid}/members/#{guid}/accounts"
+      options.merge(:endpoint => endpoint, :resource => "accounts", :klass => ::Atrium::Account)
+    end
+
     def member_body(params)
       {
         :member => {
@@ -165,5 +194,10 @@ module Atrium
         }
       }
     end
+
+    def _transaction_pagination_options(options)
+      endpoint = "/users/#{user_guid}/members/#{guid}/transactions"
+      options.merge(:endpoint => endpoint, :resource => "transactions", :klass => ::Atrium::Transaction)
+    end
   end
 end

data/lib/atrium/pageable.rb

@@ -0,0 +1,74 @@
+module Atrium
+  class PaginationBatch < ::Array
+    attr_accessor :total_pages, :total_entries, :current_page, :records_per_page
+  end
+
+  module Pageable
+    DEFAULT_RECORDS_PER_PAGE = 25
+
+    def make_get_request(endpoint, query_params)
+      uri = endpoint + "?" + ::URI.encode_www_form(query_params.sort)
+      ::Atrium.client.make_request(:get, uri)
+    end
+
+    def paginate(options = {})
+      records_per_page = options.fetch(:records_per_page, DEFAULT_RECORDS_PER_PAGE)
+      results = PaginationBatch.new
+      paginate_in_batches(options.merge(:limit => records_per_page)) do |batch|
+        results = batch
+      end
+      results
+    end
+
+    def paginate_each(options = {})
+      paginate_in_batches(options) do |batch|
+        batch.each do |record|
+          yield record
+        end
+      end
+    end
+
+    def paginate_in_batches(options = {})
+      fail ::ArgumentError, "A block is required" unless block_given?
+
+      endpoint = options.fetch(:endpoint)
+      resource = options.fetch(:resource)
+      klass = options.fetch(:klass, self)
+
+      query_params = options.fetch(:query_params, {})
+      limit = options.fetch(:limit, nil)
+      current_page = options.fetch(:initial_page, 1)
+      records_per_page = options.fetch(:records_per_page, DEFAULT_RECORDS_PER_PAGE)
+
+      pagination_info_query_params = query_params.merge(:records_per_page => records_per_page)
+      pagination = pagination_info(endpoint, pagination_info_query_params)
+      total_pages = pagination["total_pages"]
+      total_entries = pagination["total_entries"]
+      # "total_pages > 1" check exists since some query_params only return 1 page
+      total_pages = limit / records_per_page if limit.present? && total_pages > 1
+
+      until current_page > total_pages
+        params = query_params.merge(:page => current_page, :records_per_page => records_per_page)
+        response = make_get_request(endpoint, params)
+
+        records = response[resource].map { |attributes| klass.new(attributes) }
+
+        batch = ::Atrium::PaginationBatch.new(records)
+        batch.total_pages = total_pages
+        batch.total_entries = total_entries
+        batch.current_page = current_page
+        batch.records_per_page = records_per_page
+        yield batch
+
+        current_page += 1
+      end
+
+      nil
+    end
+
+    def pagination_info(endpoint, query_params)
+      response = make_get_request(endpoint, query_params.merge(:page => 1))
+      response["pagination"]
+    end
+  end
+end

data/lib/atrium/transaction.rb

@@ -1,5 +1,6 @@
 module Atrium
   class Transaction
+    extend ::Atrium::Pageable
     include ::ActiveAttr::Model
 
     attribute :account_guid
@@ -31,20 +32,31 @@ module Atrium
     attribute :updated_at
     attribute :user_guid
 
-    def self.list(user_guid:)
-      endpoint = "/users/#{user_guid}/transactions"
-      raw_transactions = ::Atrium.client.make_request(:get, endpoint)
+    def self.list(options = {})
+      options = _transaction_pagination_options(options)
+      paginate(options)
+    end
+
+    def self.list_each(options = {})
+      options = _transaction_pagination_options(options)
+      paginate_each(options) { |transaction| yield transaction }
+    end
 
-      raw_transactions["transactions"].map do |raw_transaction|
-        ::Atrium::Transaction.new(raw_transaction)
-      end
+    def self.list_in_batches(options = {})
+      options = _transaction_pagination_options(options)
+      paginate_in_batches(options) { |batch| yield batch }
     end
 
     def self.read(user_guid:, transaction_guid:)
       endpoint = "/users/#{user_guid}/transactions/#{transaction_guid}"
       raw_transaction = ::Atrium.client.make_request(:get, endpoint)
-
       ::Atrium::Transaction.new(raw_transaction["transaction"])
     end
+
+    def self._transaction_pagination_options(options)
+      user_guid = options.fetch(:user_guid)
+      endpoint = "/users/#{user_guid}/transactions"
+      options.merge(:endpoint => endpoint, :resource => "transactions")
+    end
   end
 end

data/lib/atrium/user.rb

@@ -1,5 +1,6 @@
 module Atrium
   class User
+    extend ::Atrium::Pageable
     include ::ActiveAttr::Model
 
     # ATTRIBUTES
@@ -20,13 +21,19 @@ module Atrium
       ::Atrium::User.new(user_params)
     end
 
-    def self.list
-      endpoint = "/users"
-      users_response = ::Atrium.client.make_request(:get, endpoint)
+    def self.list(options = {})
+      options = _user_pagination_options(options)
+      paginate(options)
+    end
+
+    def self.list_each(options = {})
+      options = _user_pagination_options(options)
+      paginate_each(options) { |user| yield user }
+    end
 
-      users_response["users"].map do |user|
-        ::Atrium::User.new(user)
-      end
+    def self.list_in_batches(options = {})
+      options = _user_pagination_options(options)
+      paginate_in_batches(options) { |batch| yield batch }
     end
 
     def self.read(guid:)
@@ -40,13 +47,19 @@ module Atrium
     ##
     # INSTANCE METHODS
     #
-    def accounts
-      endpoint = "/users/#{guid}/accounts"
-      response = ::Atrium.client.make_request(:get, endpoint)
+    def accounts(options = {})
+      options = _account_pagination_options(options)
+      self.class.paginate(options)
+    end
 
-      response["accounts"].map do |account|
-        ::Atrium::Account.new(account)
-      end
+    def each_account(options = {})
+      options = _account_pagination_options(options)
+      self.class.paginate_each(options) { |account| yield account }
+    end
+
+    def accounts_in_batches(options = {})
+      options = _account_pagination_options(options)
+      self.class.paginate_in_batches(options) { |batch| yield batch }
     end
 
     def delete
@@ -56,22 +69,34 @@ module Atrium
       self
     end
 
-    def members
-      endpoint = "/users/#{guid}/members"
-      response = ::Atrium.client.make_request(:get, endpoint)
+    def members(options = {})
+      options = _member_pagination_options(options)
+      self.class.paginate(options)
+    end
 
-      response["members"].map do |member|
-        ::Atrium::Member.new(member)
-      end
+    def each_member(options = {})
+      options = _member_pagination_options(options)
+      self.class.paginate_each(options) { |member| yield member }
     end
 
-    def transactions
-      endpoint = "/users/#{guid}/transactions"
-      response = ::Atrium.client.make_request(:get, endpoint)
+    def members_in_batches(options = {})
+      options = _member_pagination_options(options)
+      self.class.paginate_in_batches(options) { |batch| yield batch }
+    end
 
-      response["transactions"].map do |transaction|
-        ::Atrium::Transaction.new(transaction)
-      end
+    def transactions(options = {})
+      options = _transaction_pagination_options(options)
+      self.class.paginate(options)
+    end
+
+    def each_transaction(options = {})
+      options = _transaction_pagination_options(options)
+      self.class.paginate_each(options) { |transaction| yield transaction }
+    end
+
+    def transactions_in_batches(options = {})
+      options = _transaction_pagination_options(options)
+      self.class.paginate_in_batches(options) { |batch| yield batch }
     end
 
     def update(params)
@@ -84,8 +109,27 @@ module Atrium
       self
     end
 
+    def self._user_pagination_options(options)
+      options.merge(:endpoint => "/users", :resource => "users")
+    end
+
   private
 
+    def _account_pagination_options(options)
+      endpoint = "/users/#{guid}/accounts"
+      options.merge(:endpoint => endpoint, :resource => "accounts", :klass => ::Atrium::Account)
+    end
+
+    def _member_pagination_options(options)
+      endpoint = "/users/#{guid}/members"
+      options.merge(:endpoint => endpoint, :resource => "members", :klass => ::Atrium::Member)
+    end
+
+    def _transaction_pagination_options(options)
+      endpoint = "/users/#{guid}/transactions"
+      options.merge(:endpoint => endpoint, :resource => "transactions", :klass => ::Atrium::Transaction)
+    end
+
     def update_params(params)
       {
         :user => params

data/lib/atrium/version.rb

@@ -1,3 +1,3 @@
 module Atrium
-  VERSION = "0.5.0".freeze
+  VERSION = "1.0.1".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atrium-ruby
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Jon Carstens, Dan Jones, Zach Toolson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-08-07 00:00:00.000000000 Z
+date: 2017-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_attr
@@ -176,6 +176,7 @@ files:
 - lib/atrium/error.rb
 - lib/atrium/institution.rb
 - lib/atrium/member.rb
+- lib/atrium/pageable.rb
 - lib/atrium/paginate.rb
 - lib/atrium/ruby.rb
 - lib/atrium/transaction.rb
@@ -201,7 +202,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Ruby wrapper for the Atrium API by MX