gun_broker 1.3.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 37428cdf48dee77029ac60d1d952c99f4a3cc8bb
-  data.tar.gz: 67b8e2d282ba3d25e79cbd942c9100892e54bb68
+  metadata.gz: c7c5d35e48c658ec3bb20f91f9324d87689576eb
+  data.tar.gz: 190619c274d40d9ca6c5ebc3b4a006262d8655ee
 SHA512:
-  metadata.gz: 4f7fb34d4e93485b7f326df30229ff2f0126fc1703acc2dd5e56180ac7f170f238244822b0f61231dd5f60b2b23a2cf4e3fcacd6eb7127738e892a3bdf5f9d8e
-  data.tar.gz: 3ff24c0755be1b05abe2ac403534fb9c59ea92acb56e76819f05dc83445ac6474471ce135aad5afc3bc132938d70d13478150e10cd531f40ed8304105ab456b5
+  metadata.gz: 560eab3e870fb03dd1f02909b89506a9e9f85b39199475081761811f23ce8b3c15eaa0a98bac1e6e32776949e679aa995aa62898da3be94956b20021e0a09688
+  data.tar.gz: 298d96e0ceb32d73c4b397a6049db34b0544aa411d19b07e3895fe821f7e2f9564721cd0d03960ecb8b9f5291248bca54792ae4b3d2dc827ca0ee279890bfb8c

data/lib/gun_broker.rb

@@ -6,6 +6,8 @@ require 'gun_broker/error'
 require 'gun_broker/feedback'
 require 'gun_broker/item'
 require 'gun_broker/items_as_page'
+require 'gun_broker/order'
+require 'gun_broker/orders_as_page'
 require 'gun_broker/response'
 require 'gun_broker/user'
 

data/lib/gun_broker/api.rb

@@ -15,8 +15,8 @@ module GunBroker
     # Used to return the maximum number of results from paginated responses.
     PAGE_SIZE = 300
 
-    # Defaults to 12 (View Last 30 Days), so we need to specify 1 (View All Completed) to get everything.
-    TIME_FRAME_FOR_ALL_RESULTS = 1
+    MAX_ITEMS_TIME_FRAME = 1
+    MAX_ORDERS_TIME_FRAME = 7
 
     USER_AGENT = "gun_broker rubygems.org/gems/gun_broker v(#{GunBroker::VERSION})"
 

data/lib/gun_broker/order.rb

@@ -0,0 +1,106 @@
+module GunBroker
+  # Represents a GunBroker order (listing).
+  class Order
+
+    # TODO: Refactor this, #attributes, and #[] into a module.
+    # @return [Hash] Attributes parsed from the JSON response.
+    attr_reader :attrs
+
+    # @param order_id [Integer, String] The ID of the Order to find.
+    # @return [Order] An Order instance or `nil` if no Order with `order_id` exists.
+    def self.find(order_id, params = {}, headers = {})
+      find!(order_id, params, headers)
+    rescue GunBroker::Error::NotFound
+      nil
+    end
+
+    # Same as {.find} but raises GunBroker::Error::NotFound if no Order is found.
+    # @param (see .find)
+    # @raise [GunBroker::Error::NotFound] If no Order with `order_id` exists.
+    # @return (see .find)
+    def self.find!(order_id, params = {}, headers = {})
+      response = GunBroker::API.get("/Orders/#{order_id}", params, headers)
+      new(response.body)
+    end
+
+    # @param attrs [Hash] The JSON attributes from the API response.
+    def initialize(attrs = {})
+      @attrs = attrs
+    end
+
+    # @return [Hash] Attributes parsed from the JSON response.
+    def attributes
+      @attrs
+    end
+
+    # @return [Integer] The Order ID.
+    def id
+      @attrs['orderID']
+    end
+
+    # @return [String] FFL Number (if applicable) for this Order.
+    def ffl_number
+      @attrs['fflNumber']
+    end
+
+    # @return [Array] Item IDs of associated items for this Order.
+    def item_ids
+      @attrs['itemIDs']
+    end
+
+    # @return [Hash] Billing info for this Order.
+    def bill_to
+      {
+        name:         @attrs['billToName'],
+        address_1:    @attrs['billToAddress1'],
+        address_2:    @attrs['billToAddress2'],
+        city:         @attrs['billToCity'],
+        state:        @attrs['billToState'],
+        zip:          @attrs['billToPostalCode'],
+        email:        @attrs['billToEmail'],
+        phone:        @attrs['billToPhone']
+      }
+    end
+
+    # @return [Hash] Shipping info for this Order.
+    def ship_to
+      {
+        name:         @attrs['shipToName'],
+        address_1:    @attrs['shipToAddress1'],
+        address_2:    @attrs['shipToAddress2'],
+        city:         @attrs['shipToCity'],
+        state:        @attrs['shipToState'],
+        zip:          @attrs['shipToPostalCode'],
+        email:        @attrs['shipToEmail'],
+        phone:        @attrs['shipToPhone']
+      }
+    end
+
+    # @return [Float] Total shipping amount for this Order.
+    def shipping_total
+      @attrs['shipCost']
+    end
+
+    # @return [Float] Total sales tax for this Order.
+    def sales_tax_toal
+      @attrs['salesTaxTotal']
+    end
+
+    # @return [Float] Total sales amount for this Order.
+    def order_total
+      @attrs['orderTotal']
+    end
+
+    # @return [String] Payment methods used for this Order.
+    def payment_methods
+      @attrs['paymentMethod'].values
+    end
+
+    # @param key [String] An Order attribute name (from the JSON response).
+    # @return The value of the given `key` or `nil`.
+    def [](key)
+      @attrs[key]
+    end
+
+  end
+end

data/lib/gun_broker/orders_as_page.rb

@@ -0,0 +1,22 @@
+module GunBroker
+  # Represents a page of GunBroker orders.
+  class OrdersAsPage
+
+    # @param attrs [Hash] The attributes required to fetch orders from the API.
+    def initialize(attributes = {})
+      @attributes = attributes
+    end
+
+    # @return [Array<Order>]
+    def fetch_orders
+      @attributes[:params].merge!({
+        'PageIndex' => @attributes[:page_index],
+        'PageSize'  => @attributes[:page_size],
+      })
+      response = GunBroker::API.get(@attributes[:endpoint], @attributes[:params], @attributes[:token_header])
+
+      response['results'].map { |result| GunBroker::Order.new(result) }
+    end
+
+  end
+end

data/lib/gun_broker/user.rb

@@ -1,6 +1,8 @@
 require 'gun_broker/token_header'
 require 'gun_broker/user/items_delegate'
 require 'gun_broker/user/items_as_pages_delegate'
+require 'gun_broker/user/orders_delegate'
+require 'gun_broker/user/orders_as_pages_delegate'
 
 module GunBroker
   # Represents a GunBroker User.
@@ -94,6 +96,20 @@ module GunBroker
       @items_as_pages_delegate ||= ItemsAsPagesDelegate.new(self, options)
     end
 
+    # (see OrdersDelegate)
+    # See the {OrdersDelegate} docs.
+    # @return [OrdersDelegate]
+    def orders
+      @orders_delegate ||= OrdersDelegate.new(self)
+    end
+
+    # (see OrdersAsPagesDelegate)
+    # See the {OrdersAsPagesDelegate} docs.
+    # @return [OrdersAsPagesDelegate]
+    def orders_as_pages(options = {})
+      @orders_as_pages_delegate ||= OrdersAsPagesDelegate.new(self, options)
+    end
+
     private
 
     # @return [Boolean] `true` if `@username` is present and either `@password` *or* `@token` is present.

data/lib/gun_broker/user/items_as_pages_delegate.rb

@@ -99,7 +99,7 @@ module GunBroker
         when :sellername
           { 'SellerName' => @user.username }
         when :timeframe
-          { 'TimeFrame' => GunBroker::API::TIME_FRAME_FOR_ALL_RESULTS }
+          { 'TimeFrame' => GunBroker::API::MAX_ITEMS_TIME_FRAME }
         else
           raise GunBroker::Error.new 'Unrecognized `params_for` key.'
         end

data/lib/gun_broker/user/items_delegate.rb

@@ -180,7 +180,7 @@ module GunBroker
         when :sellername
           { 'SellerName' => @user.username }
         when :timeframe
-          { 'TimeFrame' => GunBroker::API::TIME_FRAME_FOR_ALL_RESULTS }
+          { 'TimeFrame' => GunBroker::API::MAX_ITEMS_TIME_FRAME }
         when :itemid
           { 'ItemID' => (options[:item_id] || options["ItemID"]) }
         else

data/lib/gun_broker/user/orders_as_pages_delegate.rb

@@ -0,0 +1,56 @@
+require 'gun_broker/token_header'
+
+module GunBroker
+  class User
+    # Used to scope {OrdersAsPage} actions by {User}.
+    class OrdersAsPagesDelegate
+
+      include GunBroker::TokenHeader
+
+      # @param user [User] A {User} instance to scope order pages by.
+      # @param options [Hash] { orders_per_page => <number of desired orders per page> (Integer) }.
+      def initialize(user, options = {})
+        max_page_size = GunBroker::API::PAGE_SIZE
+        @user = user
+        @orders_per_page = options.fetch(:orders_per_page, max_page_size)
+
+        if @orders_per_page > max_page_size
+          raise ArgumentError.new("`orders_per_page` may not exceed #{max_page_size}")
+        end
+      end
+
+      # Returns pages for orders the User has sold.
+      # @note {API#get! GET} /OrdersSold
+      # @return [Array<OrdersAsPage>]
+      def sold
+        @sold ||= build_pages_for(:OrdersSold, { 'TimeFrame' => GunBroker::API::MAX_ORDERS_TIME_FRAME })
+      end
+
+      private
+
+      def build_pages_for(endpoint, params = {})
+        endpoint = ['/', endpoint.to_s].join
+        _token_header = token_header(@user.token)
+        response = GunBroker::API.get(endpoint, params.merge({ 'PageSize' => 1 }), _token_header)
+        number_of_pages = (response['count'] / @orders_per_page.to_f).ceil
+        orders_as_pages = []
+
+        number_of_pages.times do |page_number|
+          page_number += 1
+          attrs = {
+            page_size:    @orders_per_page,
+            page_index:   page_number,
+            endpoint:     endpoint,
+            params:       params,
+            token_header: _token_header
+          }
+
+          orders_as_pages << GunBroker::OrdersAsPage.new(attrs)
+        end
+
+        orders_as_pages
+      end
+
+    end
+  end
+end

data/lib/gun_broker/user/orders_delegate.rb

@@ -0,0 +1,94 @@
+require 'gun_broker/token_header'
+
+module GunBroker
+  class User
+    # Used to scope {Order} actions by {User}.
+    class OrdersDelegate
+
+      include GunBroker::TokenHeader
+
+      # @param user [User] A {User} instance to scope orders by.
+      def initialize(user)
+        @user = user
+      end
+
+      # Finds a specific User's Order by ID. Calls {Order.find} to get full Order details.
+      # @raise (see #sold)
+      # @return [Order] Returns the Order or `nil` if no Order found.
+      def find(order_id)
+        GunBroker::Order.find(order_id, {}, token_header(@user.token))
+      end
+
+      # Same as {#find} but raises GunBroker::Error::NotFound if no order is found.
+      # @raise [GunBroker::Error::NotFound] If the User has no Order with `order_id`.
+      # @return [Order] Returns the Order.
+      def find!(order_id)
+        order = find(order_id)
+        raise GunBroker::Error::NotFound.new("Couldn't find order with ID '#{order_id}'") if order.nil?
+        order
+      end
+
+      # Sold Orders for the User.
+      # @param options [Hash] {ItemID=>ItemID}
+      # @note {API#get! GET} /OrdersSold
+      # @return [Array<Order>]
+      def sold(options = {})
+        params = [
+          *params_for(:timeframe),
+          *params_for(:itemid, options)
+        ].to_h
+
+        @sold ||= fetch_orders(:OrdersSold, params)
+      end
+
+      private
+
+      def fetch_orders(endpoint, params = {})
+        cleanup_nil_params(params)
+        params.merge!('PageSize' => GunBroker::API::PAGE_SIZE)
+
+        endpoint = ['/', endpoint.to_s].join
+        response = GunBroker::API.get(endpoint, params, token_header(@user.token))
+        number_of_pages = (response['count'] / GunBroker::API::PAGE_SIZE.to_f).ceil
+
+        if number_of_pages > 1
+          _orders_from_results = orders_from_results(response['results'])
+
+          number_of_pages.times do |page_number|
+            page_number += 1
+            next if page_number == 1
+
+            params.merge!({ 'PageIndex' => page_number })
+            response = GunBroker::API.get(endpoint, params, token_header(@user.token))
+            _orders_from_results.concat(orders_from_results(response['results']))
+          end
+
+          _orders_from_results
+        else
+          orders_from_results(response['results'])
+        end
+      end
+
+      def orders_from_results(results)
+        # TODO: Ignore non-US orders.
+        results.map { |result| GunBroker::Order.new(result) }
+      end
+
+      def params_for(key, options = {})
+        case key
+        when :timeframe
+          { 'TimeFrame' => GunBroker::API::MAX_ORDERS_TIME_FRAME }
+        when :itemid
+          { 'ItemID' => (options[:item_id] || options["ItemID"]) }
+        else
+          raise GunBroker::Error.new 'Unrecognized `params_for` key.'
+        end
+      end
+
+      def cleanup_nil_params(params)
+        params.delete_if { |k, v| v.nil? }
+      end
+
+    end
+  end
+end

data/lib/gun_broker/version.rb

@@ -1,3 +1,3 @@
 module GunBroker
-  VERSION = "1.3.2"
+  VERSION = "1.4.0"
 end

data/spec/gun_broker/user/items_delegate_spec.rb

@@ -160,7 +160,7 @@ describe GunBroker::User::ItemsDelegate do
             headers: headers('X-AccessToken' => token),
             query: {
               'PageSize'  => GunBroker::API::PAGE_SIZE,
-              'TimeFrame' => GunBroker::API::TIME_FRAME_FOR_ALL_RESULTS,
+              'TimeFrame' => GunBroker::API::MAX_ITEMS_TIME_FRAME,
             }
           )
           .to_return(body: response_fixture('items'))
@@ -178,7 +178,7 @@ describe GunBroker::User::ItemsDelegate do
             headers: headers('X-AccessToken' => token),
             query: {
               'PageSize'  => GunBroker::API::PAGE_SIZE,
-              'TimeFrame' => GunBroker::API::TIME_FRAME_FOR_ALL_RESULTS,
+              'TimeFrame' => GunBroker::API::MAX_ITEMS_TIME_FRAME,
             }
           )
           .to_return(body: response_fixture('not_authorized'), status: 401)
@@ -199,7 +199,7 @@ describe GunBroker::User::ItemsDelegate do
             headers: headers('X-AccessToken' => token),
             query: {
               'PageSize'  => GunBroker::API::PAGE_SIZE,
-              'TimeFrame' => GunBroker::API::TIME_FRAME_FOR_ALL_RESULTS,
+              'TimeFrame' => GunBroker::API::MAX_ITEMS_TIME_FRAME,
             }
           )
           .to_return(body: response_fixture('items'))
@@ -216,7 +216,7 @@ describe GunBroker::User::ItemsDelegate do
             query: {
               'PageSize'  => GunBroker::API::PAGE_SIZE,
               'ItemID'    => '123',
-              'TimeFrame' => GunBroker::API::TIME_FRAME_FOR_ALL_RESULTS,
+              'TimeFrame' => GunBroker::API::MAX_ITEMS_TIME_FRAME,
             }
           )
           .to_return(body: response_fixture('item_id'))
@@ -234,7 +234,7 @@ describe GunBroker::User::ItemsDelegate do
             headers: headers('X-AccessToken' => token),
             query: {
               'PageSize'  => GunBroker::API::PAGE_SIZE,
-              'TimeFrame' => GunBroker::API::TIME_FRAME_FOR_ALL_RESULTS,
+              'TimeFrame' => GunBroker::API::MAX_ITEMS_TIME_FRAME,
             }
           )
           .to_return(body: response_fixture('not_authorized'), status: 401)
@@ -255,7 +255,7 @@ describe GunBroker::User::ItemsDelegate do
             headers: headers('X-AccessToken' => token),
             query: {
               'PageSize'  => GunBroker::API::PAGE_SIZE,
-              'TimeFrame' => GunBroker::API::TIME_FRAME_FOR_ALL_RESULTS,
+              'TimeFrame' => GunBroker::API::MAX_ITEMS_TIME_FRAME,
             }
           )
           .to_return(body: response_fixture('items'))
@@ -273,7 +273,7 @@ describe GunBroker::User::ItemsDelegate do
             headers: headers('X-AccessToken' => token),
             query: {
               'PageSize'  => GunBroker::API::PAGE_SIZE,
-              'TimeFrame' => GunBroker::API::TIME_FRAME_FOR_ALL_RESULTS,
+              'TimeFrame' => GunBroker::API::MAX_ITEMS_TIME_FRAME,
             }
           )
           .to_return(body: response_fixture('not_authorized'), status: 401)
@@ -294,7 +294,7 @@ describe GunBroker::User::ItemsDelegate do
             headers: headers('X-AccessToken' => token),
             query: {
               'PageSize'  => GunBroker::API::PAGE_SIZE,
-              'TimeFrame' => GunBroker::API::TIME_FRAME_FOR_ALL_RESULTS,
+              'TimeFrame' => GunBroker::API::MAX_ITEMS_TIME_FRAME,
             }
           )
           .to_return(body: response_fixture('items'))
@@ -312,7 +312,7 @@ describe GunBroker::User::ItemsDelegate do
             headers: headers('X-AccessToken' => token),
             query: {
               'PageSize'  => GunBroker::API::PAGE_SIZE,
-              'TimeFrame' => GunBroker::API::TIME_FRAME_FOR_ALL_RESULTS,
+              'TimeFrame' => GunBroker::API::MAX_ITEMS_TIME_FRAME,
             }
           )
           .to_return(body: response_fixture('not_authorized'), status: 401)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gun_broker
 version: !ruby/object:Gem::Version
-  version: 1.3.2
+  version: 1.4.0
 platform: ruby
 authors:
 - Dale Campbell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-22 00:00:00.000000000 Z
+date: 2018-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -137,11 +137,15 @@ files:
 - lib/gun_broker/item.rb
 - lib/gun_broker/item/constants.rb
 - lib/gun_broker/items_as_page.rb
+- lib/gun_broker/order.rb
+- lib/gun_broker/orders_as_page.rb
 - lib/gun_broker/response.rb
 - lib/gun_broker/token_header.rb
 - lib/gun_broker/user.rb
 - lib/gun_broker/user/items_as_pages_delegate.rb
 - lib/gun_broker/user/items_delegate.rb
+- lib/gun_broker/user/orders_as_pages_delegate.rb
+- lib/gun_broker/user/orders_delegate.rb
 - lib/gun_broker/version.rb
 - spec/fixtures/authenticate.json
 - spec/fixtures/categories.json