bigcommerce 1.0.0.beta → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d098924abf4c82d2daa1a8dfdd09068a8960e771
-  data.tar.gz: d31b1ab3c0f9c52df72d16c06a00c72f615e21e0
+  metadata.gz: f89e22fe6e4042c5231912f0594eccc6e20cf2d2
+  data.tar.gz: e72dc04e6ea9894c47740882e89edfc14ceb84ae
 SHA512:
-  metadata.gz: 4b520cad6ba40ea401e4a79e15ed7d0308dc8d87599382a6cb6b02972b4e30729351832cbbccedff8054fae635b6d769c0d9970528ed448d90e5a21de483602f
-  data.tar.gz: 81357d00e6c8cd9eec5a2d8123c68c33c36b7bb686369d82e80e30b8cbb6b9b378041f54cd21d64878e53508cedd613cb7d0aab8c4fb1183c1f04f6eb18e66ae
+  metadata.gz: ab56f2ab83b837201fc23c4e749633b47702a0ef48d081854b14ce220760f130675200a1513f2a8ba516419a2cf44b2e2da120289ab458130de333e5756f8077
+  data.tar.gz: b35e6c9009776ad58a0565d8d8785de254dfba5f1cadd10980c8c133d7fa70038485008c15bbcd6cf9f5f11f8e886b940c45ce269cb8e9a51e995207a70a53c9

data/README.md

@@ -1,83 +1,79 @@
-# Bigcommerce
+# BigCommerce API Ruby
 
-[![Gem Version](https://badge.fury.io/rb/bigcommerce.png)](https://rubygems.org/gems/bigcommerce)
-[![Build Status](https://travis-ci.org/bigcommerce/bigcommerce-api-ruby.png?branch=master)](https://travis-ci.org/bigcommerce/bigcommerce-api-ruby)
-[![Dependency Status](https://gemnasium.com/bigcommerce/bigcommerce-api-ruby.png?travis)](https://gemnasium.com/bigcommerce/bigcommerce-api-ruby)
-[![Code Climate](https://codeclimate.com/github/bigcommerce/bigcommerce-api-ruby.png)](https://codeclimate.com/github/bigcommerce/bigcommerce-api-ruby)
-[![Coverage Status](https://coveralls.io/repos/bigcommerce/bigcommerce-api-ruby/badge.png?branch=master)](https://coveralls.io/r/bigcommerce/bigcommerce-api-ruby?branch=master)
+[![Gem Version](https://badge.fury.io/rb/bigcommerce.svg)](https://rubygems.org/gems/bigcommerce)
+[![Build Status](https://travis-ci.org/bigcommerce/bigcommerce-api-ruby.svg?branch=master)](https://travis-ci.org/bigcommerce/bigcommerce-api-ruby)
+[![Dependency Status](https://gemnasium.com/bigcommerce/bigcommerce-api-ruby.svg?travis)](https://gemnasium.com/bigcommerce/bigcommerce-api-ruby)
 
-This is the official Bigcommerce API client to support our Rest API. You can find more information about becoming a Bigcommerce developer here: [developer.bigcommerce.com](http://developer.bigcommerce.com).
-
-#### ⚠️ A note about the current client: ⚠️
-This is a preview release of the 1.0.0 version of the Bigcommerce API Client. Please report issues if they come up.
-
-We have introduced a new major version of the API client and it is a complete rewrite (for the better). If you want to see the old version of the API client, please view it here: [Bigcommerce API client v0.x](https://github.com/bigcommerce/bigcommerce-api-ruby/tree/0.x). We recommend that developers upgrade to the latest client, but we will still support our developers who are unable to upgrade.
+This is the official BigCommerce API client to support our Stores API. You can find more information about becoming a BigCommerce developer here: [developer.bigcommerce.com](http://developer.bigcommerce.com).
 
 
 ## Installation
-Bigcommerce is available on Rubygems:
+BigCommerce is available on [RubyGems](https://rubygems.org/gems/bigcommerce).
 
 ```sh
-gem install bigcommerce --pre
+gem install bigcommerce
 ```
 
 You can also add it to your Gemfile.
 
 ```rb
-gem 'bigcommerce', '>= 1.0.0.beta'
+gem 'bigcommerce', '~> 1.0'
 ```
 
+## Requirements
+- Ruby 2.0.0 or newer. Please refer to the `.travis.yml` to see which versions we officially support.
+
 ## Getting Started
-In order to make requests to our API, you must register as a developer and have your credentials ready.
+To make requests to our API, you must register as a developer and have your credentials ready.
 
-We currently have two different authentication schemes you can use depending on your use-case.
+Also very important: For the OAuth authentication mechanism, the resources to which you have acccess depend on the scopes that the merchant has granted to your application. For more information about Store API scopes, see: [OAuth Scopes](https://developer.bigcommerce.com/api/scopes).
 
-#### Public Apps
-Public apps can be submitted to Bigcommerce App Store, allowing other businesses to install it in their Bigcommerce stores.
+## Authentication
+We currently have two different authentication schemes that you can select, depending on your use case.
 
-[More Information](https://developer.bigcommerce.com/api/using-oauth-intro)
+### OAuth
+OAuth apps can be submitted to [BigCommerce App Store](https://www.bigcommerce.com/apps), allowing other merchants to install these apps in their BigCommerce stores.
 
-#### Private Apps
-To develop a custom integration for one store, your app needs to use Basic Authentication.
+__[More Information](https://developer.bigcommerce.com/api/using-oauth-intro)__
 
-[More Information](https://developer.bigcommerce.com/api/legacy/basic-auth)
+### Basic Authentication (Legacy)
+To develop a custom integration for one store, your app needs to use Basic Authentication.
 
-## Usage
-For full examples on using the API client, please see the [examples folder](examples).
+__[More Information](https://developer.bigcommerce.com/api/legacy/basic-auth)__
 
 ## Configuration
-In order to authenticate the API client, you will need to configure the client like this:
+To authenticate your API client, you will need to configure the client like the following examples.
 
-#### Single Click (Public Apps):
+### OAuth App
 
-- ```client_id```: Obtained from the "My Apps" section on the [developer portal](http://developer.bigcommerce.com).
+- ```client_id```: Obtained from the on the BigCommerce [Developer Portal's](http://developer.bigcommerce.com) "My Apps" section.
 - ```access_token```: Obtained after a token exchange in the auth callback.
 - ```store_hash```: Also obtained after the token exchange.
 
 ```rb
 Bigcommerce.configure do |config|
-  config.store_hash = 'store_hash'
-  config.client_id = 'client_id'
-  config.access_token = 'access_token'
+  config.store_hash = ENV['BC_STORE_HASH']
+  config.client_id = ENV['BC_CLIENT_ID']
+  config.access_token = ENV['BC_ACCESS_TOKEN']
 end
 ```
 
-#### Private Apps:
+### Basic Authentication (Legacy)
 
-To get all the private app credentials, simply visit your store admin page and navigate to the Settings > Legacy API Settings. Once there, you can create a new username to authenticate with.
+To get all the basic auth credentials, simply visit your store admin page, and navigate to the `Advanced Settings` > `Legacy API Settings`. Once there, you can create a new legacy API account on which to authenticate.
 
 ```rb
 Bigcommerce.configure do |config|
   config.auth = 'legacy'
-  config.url = 'https://api_path.com'
-  config.username = 'username'
-  config.api_key = 'api_key'
+  config.url = ENV['BC_API_ENDPOINT_LEGACY']
+  config.username = ENV['BC_USERNAME']
+  config.api_key = ENV['BC_API_KEY']
 end
 ```
 
-__SSL Configuration:__
+__SSL Configuration__
 
-If you are using your own self-signed certificate, you can pass SSL options to Faraday. This is not required, but may be useful in special edge cases.
+If you are using your own, self-signed, certificate, you can pass SSL options to Faraday. This is not required, but might be useful in special edge cases.
 
 ```rb
 Bigcommerce.configure do |config|
@@ -94,7 +90,87 @@ end
 For more information about configuring SSL with Faraday, please see the following:
 
 - [Faraday SSL example](https://gist.github.com/mislav/938183)
-- [Setting up SSL certificates](https://github.com/lostisland/faraday/wiki/Setting-up-SSL-certificates)
+- [Faraday: Setting up SSL certificates](https://github.com/lostisland/faraday/wiki/Setting-up-SSL-certificates)
+
+### Customer Login API
+If you want to generate tokens for storefront login using the Customer Login API, you need to configure your app's client secret.
+
+- ```store_hash```: The store hash of the store you are operating against.
+- ```client_id```: Obtained from the on the BigCommerce [Developer Portal's](http://developer.bigcommerce.com) "My Apps" section.
+- ```client_secret```: Obtained from the on the BigCommerce [Developer Portal's](http://developer.bigcommerce.com) "My Apps" section.
+
+```rb
+Bigcommerce.configure do |config|
+  config.store_hash = ENV['BC_STORE_HASH']
+  config.client_id = ENV['BC_CLIENT_ID']
+  config.client_secret = ENV['BC_CLIENT_SECRET']
+end
+```
+
+## Usage
+For full examples of using the API client, please see the [examples folder](examples) and refer to BigCommerce's [developer documentation](https://developer.bigcommerce.com/api).
+
+Example:
+
+```rb
+# Configure the client to talk to a given store
+Bigcommerce.configure do |config|
+  config.store_hash = ENV['BC_STORE_HASH']
+  config.client_id = ENV['BC_CLIENT_ID']
+  config.access_token = ENV['BC_ACCESS_TOKEN']
+end
+
+# Make an API request for a given resource
+Bigcommerce::System.time
+=> #<Bigcommerce::System time=1466801314>
+```
+
+### Thread Safety
+
+The `Bigcommerce.configure` method is NOT thread-safe. This mechanism is designed for applications or CLI's (command-line interfaces) where thread safety is not a concern. If you need to guarantee thread safety, we support this alternative mechanism to make thread-safe API requests:
+
+Rather then setting up a single `connection` for all API requests, you would construct a new connection for each thread. If you can ensure that each of these connections is stored in a thread-safe manner, you can pass the `connection` as you query the resource.
+
+This connection is nothing more than a `Faraday::Connection` – so if you want to write your own, or to use your own adapters, you can feel free. Please refer to this gem's [connection class](https://github.com/bigcommerce/bigcommerce-api-ruby/blob/master/lib/bigcommerce/connection.rb) for more details.
+
+##### OAuth
+
+```rb
+connection = Bigcommerce::Connection.build(
+  Bigcommerce::Config.new(
+    store_hash: ENV['BC_STORE_HASH'],
+    client_id: ENV['BC_CLIENT_ID'],
+    access_token: ENV['BC_ACCESS_TOKEN']
+  )
+)
+=> #<Faraday::Connection:0x007fbf95068978 ... >>
+
+Bigcommerce::System.time(connection: connection)
+=> #<Bigcommerce::System time=1466546702>
+
+Bigcommerce::System.raw_request(:get, 'time', connection: connection)
+=> #<Faraday::Response:0x007fd4a4063170 ... >>
+```
+
+##### Basic Auth
+
+```rb
+connection_legacy = Bigcommerce::Connection.build(
+  Bigcommerce::Config.new(
+    auth: 'legacy',
+    url: ENV['BC_API_ENDPOINT_LEGACY'],
+    username: ENV['BC_USERNAME'],
+    api_key: ENV['BC_API_KEY']
+  )
+)
+=> #<Faraday::Connection:0x007fbf95068978 ... >>
+
+Bigcommerce::System.time(connection: connection_legacy)
+=> #<Bigcommerce::System time=1466546702>
+
+Bigcommerce::System.raw_request(:get, 'time', connection: connection_legacy)
+=> #<Faraday::Response:0x007fd4a4063170 ... >>
+```
 
 ## Contributing
 See [CONTRIBUTING.md](CONTRIBUTING.md)

data/bigcommerce.gemspec

@@ -4,25 +4,24 @@ require 'bigcommerce/version'
 
 Gem::Specification.new do |s|
   s.name = 'bigcommerce'
-  s.homepage = 'https://github.com/bigcommerce/bigcommerce-api-ruby'
-  s.authors = ['Patrick Edelman']
   s.version = Bigcommerce::VERSION
+  s.platform = Gem::Platform::RUBY
+  s.required_ruby_version = '>= 2.0.0'
   s.license = 'MIT'
 
-  s.description = 'Bigcommerce API Ruby client library. Allows developers to \
-  easily communicate with the Bigcommerce API, for either CLI tools or public \
-  apps. More info: http://developer.bigcommerce.com'
-  s.summary = 'Ruby client library for the Bigcommerce v2 API'
+  s.authors = ['BigCommerce Engineering']
+  s.homepage = 'https://github.com/bigcommerce/bigcommerce-api-ruby'
+  s.summary = 'Ruby client library for the BigCommerce API'
+  s.description = s.summary
 
-  s.required_ruby_version = '>= 1.9.3'
   s.require_paths = ['lib']
-  s.files = `git ls-files`.split($ORS)
-  s.test_files = Dir['spec/**/*.rb']
+  s.files = Dir['README.md', 'lib/**/*', 'bigcommerce.gemspec']
 
-  s.add_development_dependency 'rake'
   s.add_development_dependency 'bundler'
+  s.add_development_dependency 'rake'
 
-  s.add_dependency 'faraday'
-  s.add_dependency 'faraday_middleware'
-  s.add_dependency 'hashie'
+  s.add_dependency 'faraday', '~> 0.11'
+  s.add_dependency 'faraday_middleware', '~> 0.11'
+  s.add_dependency 'hashie', '~> 3.4'
+  s.add_dependency 'jwt', '~> 1.5.4'
 end

data/lib/bigcommerce.rb

@@ -1,6 +1,8 @@
 require 'hashie'
 require 'faraday_middleware'
 require 'bigcommerce/version'
+require 'bigcommerce/config'
+require 'bigcommerce/connection'
 require 'bigcommerce/middleware/auth'
 require 'bigcommerce/middleware/http_exception'
 require 'bigcommerce/resources/resource'
@@ -9,43 +11,12 @@ module Bigcommerce
   resources = File.join(File.dirname(__FILE__), 'bigcommerce', 'resources', '**', '*.rb')
   Dir.glob(resources, &method(:require))
 
-  DEFAULTS = {
-    base_url: 'https://api.bigcommerce.com'
-  }
-
-  HEADERS = {
-    'accept' => 'application/json',
-    'content-type' => 'application/json',
-    'user-agent' => 'bigcommerce-api-ruby'
-  }
-
   class << self
-    attr_reader :api
-    attr_accessor :api_limit
+    attr_reader :api, :config
 
     def configure
-      config = Hashie::Mash.new
-      yield(config)
-      ssl_options = config.ssl if config.auth == 'legacy'
-
-      @api = Faraday.new(url: build_url(config), ssl: ssl_options) do |conn|
-        conn.request :json
-        conn.headers = HEADERS
-        if config.auth == 'legacy'
-          conn.use Faraday::Request::BasicAuthentication, config.username, config.api_key
-        else
-          conn.use Bigcommerce::Middleware::Auth, config
-        end
-        conn.use Bigcommerce::Middleware::HttpException
-        conn.adapter Faraday.default_adapter
-      end
-    end
-
-    def build_url(config)
-      return config.url if config.auth == 'legacy'
-
-      base = ENV['BC_API_ENDPOINT'].nil? ? DEFAULTS[:base_url] : ENV['BC_API_ENDPOINT']
-      "#{base}/stores/#{config.store_hash}/v2"
+      @config = Bigcommerce::Config.new.tap { |h| yield(h) }
+      @api = Bigcommerce::Connection.build(@config)
     end
   end
 end

data/lib/bigcommerce/config.rb

@@ -0,0 +1,14 @@
+module Bigcommerce
+  class Config < Hashie::Mash
+    DEFAULTS = {
+      base_url: 'https://api.bigcommerce.com'
+    }.freeze
+
+    def api_url
+      return url if auth == 'legacy'
+
+      base = ENV['BC_API_ENDPOINT'].to_s.empty? ? DEFAULTS[:base_url] : ENV['BC_API_ENDPOINT']
+      "#{base}/stores/#{store_hash}/v2"
+    end
+  end
+end

data/lib/bigcommerce/connection.rb

@@ -0,0 +1,26 @@
+module Bigcommerce
+  module Connection
+    HEADERS = {
+      'accept' => 'application/json',
+      'content-type' => 'application/json',
+      'user-agent' => 'bigcommerce-api-ruby',
+      'accept-encoding' => 'gzip'
+    }.freeze
+
+    def self.build(config)
+      ssl_options = config.ssl || {}
+      Faraday.new(url: config.api_url, ssl: ssl_options) do |conn|
+        conn.request :json
+        conn.headers = HEADERS
+        if config.auth == 'legacy'
+          conn.use Faraday::Request::BasicAuthentication, config.username, config.api_key
+        else
+          conn.use Bigcommerce::Middleware::Auth, config
+        end
+        conn.use Bigcommerce::Middleware::HttpException
+        conn.use FaradayMiddleware::Gzip
+        conn.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/bigcommerce/exception.rb

@@ -6,19 +6,19 @@ module Bigcommerce
     end
   end
 
-  class BadRequest             < HttpError; end
-  class Unauthorized           < HttpError; end
-  class Forbidden              < HttpError; end
-  class NotFound               < HttpError; end
-  class MethodNotAllowed       < HttpError; end
-  class NotAccepted            < HttpError; end
-  class TimeOut                < HttpError; end
-  class ResourceConflict       < HttpError; end
-  class TooManyRequests        < HttpError; end
-  class InternalServerError    < HttpError; end
-  class BadGateway             < HttpError; end
-  class ServiceUnavailable     < HttpError; end
-  class GatewayTimeout         < HttpError; end
+  class BadRequest < HttpError; end
+  class Unauthorized < HttpError; end
+  class Forbidden < HttpError; end
+  class NotFound < HttpError; end
+  class MethodNotAllowed < HttpError; end
+  class NotAccepted < HttpError; end
+  class TimeOut < HttpError; end
+  class ResourceConflict < HttpError; end
+  class TooManyRequests < HttpError; end
+  class InternalServerError < HttpError; end
+  class BadGateway < HttpError; end
+  class ServiceUnavailable < HttpError; end
+  class GatewayTimeout < HttpError; end
   class BandwidthLimitExceeded < HttpError; end
 
   module HttpErrors
@@ -37,15 +37,22 @@ module Bigcommerce
       503 => Bigcommerce::ServiceUnavailable,
       504 => Bigcommerce::GatewayTimeout,
       509 => Bigcommerce::BandwidthLimitExceeded
-    }
+    }.freeze
 
     def throw_http_exception!(code, env)
       return unless ERRORS.keys.include? code
-      error_hash = env.body.empty? ? {} : JSON.parse(env.body, symbolize_names: true)
-      unless env[:response_headers]['X-Retry-After'].nil?
-        error_hash[:retry_after] = env[:response_headers]['X-Retry-After'].to_i
+      response_headers = {}
+      unless env.body.empty?
+        response_headers = begin
+          JSON.parse(env.body, symbolize_names: true)
+        rescue StandardError
+          {}
+        end
       end
-      fail ERRORS[code].new(error_hash), env.body
+      unless env[:response_headers] && env[:response_headers]['X-Retry-After'].nil?
+        response_headers[:retry_after] = env[:response_headers]['X-Retry-After'].to_i
+      end
+      raise ERRORS[code].new(response_headers), env.body
     end
   end
 end

data/lib/bigcommerce/request.rb

@@ -43,30 +43,29 @@ module Bigcommerce
     end
 
     module ClassMethods
-      def get(path, params = nil)
+      def get(path, params = {})
         response = raw_request(:get, path, params)
         build_response_object response
       end
 
-      def delete(path)
-        response = raw_request(:delete, path)
+      def delete(path, params = {})
+        response = raw_request(:delete, path, params)
         response.body
       end
 
-      def post(path, params)
+      def post(path, params = {})
         response = raw_request(:post, path, params)
         build_response_object response
       end
 
-      def put(path, params)
+      def put(path, params = {})
         response = raw_request(:put, path, params)
         build_response_object response
       end
 
-      def raw_request(method, path, params = nil)
-        response = Bigcommerce.api.send(method, path.to_s, params)
-        Bigcommerce.api_limit = response.headers['X-BC-ApiLimit-Remaining']
-        response
+      def raw_request(method, path, params = {})
+        client = params.delete(:connection) || Bigcommerce.api
+        client.send(method, path.to_s, params)
       end
 
       private