best_buy_ruby 0.1.0

data/Rakefile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+task :code_analysis do
+  sh 'bundle exec rubocop lib spec'
+  sh 'bundle exec reek lib'
+end

data/best_buy_ruby.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'lib/best_buy/base/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'best_buy_ruby'
+  spec.version       = BestBuy::Base::VERSION
+  spec.authors       = ['Sandro Damilano']
+  spec.email         = ['sandro.damilano@rootstrap.com']
+
+  spec.summary       = 'A wrapper for Best Buy APIs.'
+  spec.homepage      = 'https://github.com/rootstrap/best_buy_ruby'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/rootstrap/best_buy_ruby'
+  spec.metadata['changelog_uri'] = 'https://github.com/rootstrap/best_buy_ruby'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Production dependencies
+  spec.add_dependency 'activesupport', '~> 6.0.2.1'
+  spec.add_dependency 'faraday', '~> 1.0.0'
+
+  # Development dependencies
+  spec.add_development_dependency 'ammeter'
+  spec.add_development_dependency 'railties'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'reek'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'webmock'
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'best_buy_ruby/base'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/docs/categories_api.md

@@ -0,0 +1,25 @@
+# Categories API
+
+## The Category object
+
+Attributes:
+
+- `id`: Used to find all results within a specific category (e.g., 'abcat0100000')
+- `name`: Used to find all subcategories (e.g., parents, siblings, children) within a specific category
+- `url`: URL to corresponding BESTBUY.COM category page
+- `active`: Indicates if the category is currently active or not
+- `path`: Array of parent categories, starting with the root and finishing with the present one
+- `sub_categories`: Array of child categories. Each one is a [BaseCategory](categories_api.md#the-basecategory-object) object
+
+#### The BaseCategory object
+
+A minimalistic version of a category. Used to represent the categories in occasions where not the whole information is available (like the categories returned as `sub_categories`)
+
+Attributes:
+
+- `id`: Used to find all results within a specific category (e.g., abcat0100000)
+- `name`: Used to find all subcategories (e.g., parents, siblings, children) within a specific category
+
+## Interface
+
+(For more methods, check the [common API interface](general_overview.md#common-methods))

data/docs/general_overview.md

@@ -0,0 +1,67 @@
+# General Overview
+
+The different APIs accessible by this gem are:
+
+- [Products](products_api.md)
+- [Stores](stores_api.md)
+- [Categories](categories_api.md)
+
+In spite of having each their own specification, they all share some basics listed here.
+
+## Common interface
+
+This method can be used with any of the APIs:
+
+#### `get_all(search_query:, pagination:)`
+_alias: `index`_
+
+Retrieves a collection of items (these depend on the API). These items will be filtered by `search_query` and limited by `pagination`.
+
+Params:
+
+- `search_query`: A string representing the query added to the URL to filter the items (See [Search Techniques](https://bestbuyapis.github.io/api-documentation/#search-techniques) in the Best Buy API reference). Optional.
+- `pagination`: See [Pagination](general_overview.md#pagination). Optional.
+
+Returns: a [`CollectionsResponse`](general_overview.md#collections-response) object
+
+```ruby
+search_query = '(active=true)'
+pagination_params = { page: 2, page_size: 20 }
+
+BestBuy::Categories.new(your_api_key).get_all(search_query: search_query, pagination: pagination_params)
+```
+
+## Collections response
+
+Every request made that returns a collection of items (no matter what *kind* of item) will return an object called `CollectionsResponse`. This object contains two attributes:
+
+- `header`
+- `collection`
+
+The `collection` will contain a list of objects of the requested collection (`Product`, `Store`, etc).
+
+The `header` will be a `CollectionHeader` object which will contain some metadata of the request itself. Its attributes include:
+
+- `canonical_url`: the non-server part of the query
+- `current_page`: the page being returned
+- `partial`: flag indicating whether or not the query returned only partial results (in the event of a timeout)
+- `from`: the index of the first item returned on the current page
+- `to`: the index of the last item returned on the current page
+- `total`: the total number of items returned by the query
+- `total_pages`: the number of pages required to list all items
+- `query_time`: the time required to search the database
+- `total_time`: the time required to parse, search, format and return results
+
+## Pagination
+
+Best Buy APIs accept pagination parameters to control the amount of results returned. That's why for the `get_all` method, for example, there's an optional `pagination` parameter, which consists of a hash with two also optional keys:
+
+- `:page`: number of the page of results you’d like returned
+- `:page_size`: amount of results per page (default: 10, max: 100)
+
+Example:
+```ruby
+pagination_params = { page: 3, page_size: 50 }
+
+BestBuy::Stores.new(your_api_key).get_all(pagination: pagination_params)
+```

data/docs/products_api.md

@@ -0,0 +1,85 @@
+# Products API
+
+## The Product object
+
+Attributes:
+
+- `active`: Identifies if product is currently supported in the BESTBUY.COM catalog
+- `category_path`: A hierarchical view of a product returned as a collection
+- `alternate_categories`: Alternative categories of the product
+- `images`: An array of [Images](products_api.md#the-image-object)
+- `name`: Product name
+- `offers`: An array of [Offers](products_api.md#the-offer-object)
+- `regular_price`: Product’s regular selling price
+- `sale_price`: Current item selling price
+- `shipping_cost`: Provides product’s lowest shipping costs
+- `shipping_levels_of_service`: An array of [Shipping levels of service](products_api.md#the-shippinglevelofservice-object)
+- `sku`: Best Buy unique 7-digit product identifier
+- `type`: Best Buy product type. See [Product type details](https://bestbuyapis.github.io/api-documentation/#listing-products) in the Best Buy API reference for further information
+- `upc`: Universal Product Code (UPC)
+- `url`: URL to BESTBUY.COM product detail page
+- `raw_attributes`: Hash containing all information returned by the Best Buy API about the product. Any attribute returned not present in the object can be found here.
+
+#### The Image object
+
+Attributes:
+
+- `height`: Height of the image
+- `width`: Width of the image
+- `unit_of_measure`: Unit in which height and width are expressed
+- `href`: URL of the image
+- `primary`: If it's the main image or not
+- `rel`: Name of the image
+      
+#### The Offer object
+
+Attributes:
+
+- `id`: Offer identifier
+- `offer_name`: Offer name
+- `content_notes`: Notes about the offer
+- `start_date`: Offer start date
+- `end_date`: Offer end date
+- `text`: Offer description
+- `type`: Offer types can include: special_offer, digital_insert and deal_of_the_day (See the [oficial documentation](https://bestbuyapis.github.io/api-documentation/#offers-and-deals) for further info)
+- `url`: URL of offer information on BESTBUY.COM
+
+#### The ShippingLevelOfService object
+
+Represents the shipping options of the product, with their own prices.
+
+Attributes:
+
+- `service_level_id`: ID of the shipping level of service
+- `service_level_name`: Name of the shipping level of service
+- `unit_shipping_price`: Price of the shipping level of service
+
+## Interface
+
+(For more methods, check the [common API interface](general_overview.md#common-methods))
+
+#### `get_by(conditions)`
+
+Params:
+
+- `conditions`: A hash including certain search conditions. All of them are optional.
+
+    - `:category_id`: The ID of a category. Returns only products of that category.
+    - `:min_price`: Minimum price allowed for the returned products. It will take into account products on sale.
+    - `:max_price`: Maximum price allowed for the returned products. It will take into account products on sale.
+    - `:item_condition`: The condition all returned products must have. Can be either `new`, `pre-owned` or `refurbished`.
+    - `:pagination`: See [Pagination](general_overview.md#pagination)
+
+Returns: a [`CollectionsResponse`](general_overview.md#collections-response) object
+
+```ruby
+conditions = {
+    category_id: 'cat02015',
+    min_price: 10,
+    max_price: 15,
+    item_condition: 'new',
+    pagination: { page: 4, page_size: 100 }
+}
+
+BestBuy::Products.new(your_api_key).get_by(conditions)
+```

data/docs/stores_api.md

@@ -0,0 +1,68 @@
+# Stores API
+
+## The Store object
+
+Attributes:
+
+- `location_type`: Whether the location is a Store or a Warehouse
+- `long_name`: Full store name
+- `name`: Store name
+- `opening_time`: See [opening_time](stores_api.md#opening_time)
+- `phone`: Store phone number; phone number for Express stores goes to Best Buy Customer Service
+- `services`: Collection of services offered at each Best Buy store
+- `store_id`: Store number
+- `store_type`: Indicates the type of store, and is only present if locationType is ‘Store’. See the [official documentation](https://bestbuyapis.github.io/api-documentation/#common-attributes56) for more details
+- `store_address`: See [The Address object](stores_api.md#the-address-object)
+
+#### `opening_time`
+
+Array of hashes containing info about the opening hours for each day for the next two weeks. It has the following keys:
+
+- `:day`: Name of the day of the week (e.g.: 'Sunday')
+- `:date`: Date of the day (string formatted as: YYYY-MM-DD)
+- `:open`: Opening time (24-hour clock. E.g.: `'10:00'`. `'Close'` if the store is closed)
+- `:close`: Closing time (24-hour clock. E.g.: `'21:00'`. `'Close'` if the store is closed)
+
+#### The Address object
+
+Object that keeps all the address information of the store.
+
+Attributes:
+
+- `address`: Street address
+- `address2`: Street address 2 provides additional street address information for the Best Buy store in the result set
+- `city`: City name
+- `region`: State, territory
+- `country`: Country name
+- `postal_code`: 5-digit postal code
+- `full_postal_code`: 9-digit postal code if available for store location
+- `gmt_offset`: Time difference from GMT
+- `lat`: Latitude
+- `lng`: Longitude
+
+Note: All these attributes are accessible directly by the Store object
+
+```ruby
+store = Store.new({ address: '50 Holyoke St' })
+store.address # returns '50 Holyoke St'
+```
+
+## Interface
+
+(For more methods, check the [common API interface](general_overview.md#common-methods))
+
+#### `find(store_id)`
+
+Returns the store matching the requested ID.
+
+Params:
+
+- `store_id`: The ID of the required store
+
+Returns: a `Store` object
+
+```ruby
+store_id = 418
+
+BestBuy::Stores.new(your_api_key).find(store_id)
+```

data/lib/best_buy.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/array'
+require 'active_support/core_ext/hash'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/string'
+require 'faraday'
+
+require 'best_buy/helpers/api_helper'
+require 'best_buy/helpers/conditions/category_condition'
+require 'best_buy/helpers/conditions/max_price_condition'
+require 'best_buy/helpers/conditions/min_price_condition'
+require 'best_buy/helpers/conditions/new_condition'
+require 'best_buy/helpers/conditions/pre_owned_condition'
+require 'best_buy/helpers/conditions/refurbished_condition'
+
+require 'best_buy/base_api'
+require 'best_buy/categories'
+require 'best_buy/products'
+require 'best_buy/search_query_builder'
+require 'best_buy/stores'
+
+require 'best_buy/models/address'
+require 'best_buy/models/base_category'
+require 'best_buy/models/category'
+require 'best_buy/models/collection_header'
+require 'best_buy/models/collections_response'
+require 'best_buy/models/image'
+require 'best_buy/models/offer'
+require 'best_buy/models/product'
+require 'best_buy/models/shipping_level_of_service'
+require 'best_buy/models/store'
+
+require 'generators/best_buy/config/config_generator'

data/lib/best_buy/base.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'best_buy/base/version'
+
+module BestBuy
+  # Starting point of your gem
+  module Base
+    # Base error class
+    class Error < StandardError; end
+
+    # Your code goes here...
+  end
+end

data/lib/best_buy/base/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BestBuy
+  module Base
+    VERSION = '0.1.0'
+  end
+end

data/lib/best_buy/base_api.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module BestBuy
+  class BaseAPI
+    # All subclasses must implement:
+    # :model_class
+    # :collection_name
+    # :api_url
+
+    BASE_URL = 'https://api.bestbuy.com'
+
+    attr_reader :api_key
+
+    def initialize(api_key)
+      @api_key = api_key
+    end
+
+    def get_all(search_query: '', pagination: {})
+      request_params = {
+        apiKey: api_key,
+        format: 'json',
+        show: 'all'
+      }.merge(pagination)
+
+      response = APIHelper.new.parse_response(get_response(search_query, request_params))
+
+      CollectionsResponse.new(
+        response: response,
+        collection_name: collection_name,
+        collection_type: model_class
+      )
+    end
+    alias_method :index, :get_all
+
+    protected
+
+    def connection
+      @connection ||= Faraday.new(url: BaseAPI::BASE_URL)
+    end
+
+    def get_response(search_query, params)
+      url = URI.escape(api_url + search_query) # rubocop:disable Lint/UriEscapeUnescape
+      connection.get(url, params).body
+    end
+  end
+end

data/lib/best_buy/categories.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'best_buy'
+
+module BestBuy
+  class Categories < BaseAPI
+    CATEGORIES_API = '/v1/categories'
+
+    protected
+
+    def model_class
+      Category
+    end
+
+    def collection_name
+      :categories
+    end
+
+    def api_url
+      CATEGORIES_API
+    end
+  end
+end