ecwid_api 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f75df6f53fd6f55913cf94526d41c5cf68272ebc
-  data.tar.gz: e1a2a10f1141300974719d4998c962c617ce44c3
+  metadata.gz: 67727922f8d2fc5ab19839abda31f4ae709b67e8
+  data.tar.gz: 8e78ebe2a0dc6e83da2a9235e08a57704a04b9c4
 SHA512:
-  metadata.gz: 43e85267b0ff0a21482048c8436dc460e3045305acf73d876e0e329f8c7e90b3b62e0f76b341574735fa27e914d04ad7df7950dc44446ecd857955b54b0e6093
-  data.tar.gz: 044b281f10380c226f1e987b771297d56fa5ee6f213ccd5f4ed771cf628d37646e9c1abae4872096f29cc384b02eb3ab4298e0bd090b4eca4ecbaff122ceb06a
+  metadata.gz: f8e57e93e2c5fc0e4109955f3a1aefe311e5cf9edd868a8fb0a5feb1bca59e06eb81d07161b2f53af4c426b9eff96eacc9a4bee59adfb79c7bd4db3b82bbbe9b
+  data.tar.gz: 5065b8ba1deff18ee542f71c68ec6b478859e19fc1ca079a419cd46dac3295c6df934c9befc467d80b46fa178b6cbbb327bf82cd7a5f309e8d060a364b521509

data/README.md

@@ -2,6 +2,8 @@
 
 A gem to interface with the Ecwid REST APIs.
 
+[![Code Climate](https://codeclimate.com/github/davidbiehl/ecwid_api.png)](https://codeclimate.com/github/davidbiehl/ecwid_api)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -32,10 +34,62 @@ to be configured for each new `Client`.
       config.product_secret_key = 'PRODUCT_SECRET_KEY'
     end
 
-### Make some Requests
+## APIs
+
+### Category API
+
+The Category API will allow you to access the categories for an Ecwid store.
+An instance of the Category API is available on the client.
+
+    api = client.categories
+    # => #<EcwidApi::CategoryApi>
+
+    api.all
+    # Returns an Array of all of the `EcwidApi::Category` objects
+
+    api.root
+    # Returns an Array of the top-level `EcwidApi::Category` objects for the
+    # store
+
+    api.find(123)
+    # Returns the `EcwidApi::Category` with an ID of 123
+
+#### EcwidApi::Category Objects
+
+The properties of an `EcwidApi::Category` object can be accessed using the `[]`
+method, or with special snake_cased helper methods.
+
+    cat = client.categories.find(123)
+    # An example response from the API
+    # {
+    #   "id": 123,
+    #   "parentId": 456,
+    #   "name": "Special Category"
+    # }
+
+    cat[:id]          # Access with a Symbol
+    # => 123
+
+    cat["parentId"]   # Access with a String (case sensitive)
+    # => 456
+
+    cat.parent_id     # Access with a snake_case method
+    # => 456
+
+Each `EcwidApi::Category` also has methods to find any sub-categories, and the
+parent category, if there is one.
+
+    cat.parent
+    # Returns the parent `EcwidApi::Category`
+
+    cat.sub_categories
+    # Returns an Array of `EcwidApi::Category`
+
+### Making Ad-Hoc Requests with the Client
 
 To make a request, simply call the `#get` method on the client passing in the
-API and any parameters it requires. For example, to get some categories:
+relative path and any parameters it requires.
+For example, to get some categories:
 
     # GET https://app.ecwid.com/api/v1/[STORE-ID]/categories?parent=1
 
@@ -44,16 +98,16 @@ API and any parameters it requires. For example, to get some categories:
     # => #<Faraday::Response>
 
 The `Client` is responsible for making raw requests, which is why it returns
-a `Faraday::Response`. Eventually there will be a domain model to bury this
-detail under an abstraction. In the meantime, please see the
-[Faraday documentation](https://github.com/lostisland/faraday)
-to learn how to use the `Faraday::Response` object.
+a `Faraday::Response`. The JSON parsing middleware is also active on the Faraday
+connection, so calling `Faraday::Response#body` will return a Hash of the parsed
+JSON.
 
 ### Ecwid API Documentation
 
 The [Ecwid API documentation](http://kb.ecwid.com/w/page/25232810/API)
-should give you a good idea of what is possible to retreive. Please note that
-resources requiring the secret keys will be inaccessible until we implement
+should give you a good idea of what is possible to retreive. It also defines
+which properties are available on each of the entities it provies. Please note
+that resources requiring the secret keys will be inaccessible until we implement
 that feature.
 
 ## Contributing

data/ecwid_api.gemspec

@@ -22,4 +22,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec", "~> 2.14.1"
 
   spec.add_dependency "faraday", "~> 0.9.0"
+  spec.add_dependency "faraday_middleware", "~> 0.9.1"
 end

data/lib/ecwid_api.rb

@@ -1,4 +1,5 @@
 require "ecwid_api/version"
+require "ext/string"
 
 # Public: This is the main namespace for the EcwidApi. It can be used to store
 # the default client.
@@ -6,6 +7,10 @@ require "ecwid_api/version"
 module EcwidApi
   autoload :Client, "ecwid_api/client"
   autoload :Error, "ecwid_api/error"
+  autoload :Entity, "ecwid_api/entity"
+
+  autoload :CategoryApi, "ecwid_api/category_api"
+  autoload :Category, "ecwid_api/category"
 
   class << self
     # Public: Gets and configures a default client

data/lib/ecwid_api/category.rb

@@ -0,0 +1,14 @@
+module EcwidApi
+  class Category < Entity
+    # Public: Returns an Array of sub categories for the Category
+    def sub_categories
+      @sub_categories ||= client.categories.all(id)
+    end
+
+    # Public: Returns the parent EcwidApi::Category, or nil if there isn't one
+    def parent
+      parent_id = data["parentId"]
+      client.categories.find(parent_id) if parent_id
+    end
+  end
+end

data/lib/ecwid_api/category_api.rb

@@ -0,0 +1,62 @@
+module EcwidApi
+  # Public: This is the Ecwid API for Categories. It abstracts the end-points
+  # of the Ecwid API that deal with categories.
+  class CategoryApi
+    # Private: Gets the Client
+    attr_reader :client
+    private :client
+
+    # Public: Initializes a new EcwidApi::CategoryApi
+    #
+    # client - The EcwidApi::Client to use with the API
+    #
+    def initialize(client = EcwidApi.default_client)
+      @client = client
+      raise Error.new("The client cannot be nil") unless client
+    end
+
+    # Public: Returns all of the sub-categories for a given category
+    #
+    # See: http://kb.ecwid.com/w/page/25285101/Product%20API#RESTAPIMethodcategories
+    #
+    # parent - The Category ID of the parent category. If the parent is 0 then
+    #          a list of the root categories will be returned. If the parent is
+    #          nil, then all of the categories will be returned
+    #
+    # Returns an array of EcwidApi::Category objects
+    def all(parent = nil)
+      params = {}
+      params[:parent] = parent if parent
+
+      response = client.get("categories", params)
+
+      if response.success?
+        response.body
+      else
+        []
+      end.map {|category| Category.new(category, client: client) }
+    end
+
+    # Public: Returns an Array of the root level EcwidApi::Category objects
+    def root
+      all(0)
+    end
+
+    # Public: Returns a single EcwidApi::Category
+    #
+    # See: http://kb.ecwid.com/w/page/25285101/Product%20API#RESTAPIMethodcategory
+    #
+    # category_id - A Category ID to get
+    #
+    # Returns an EcwidApi::Category, or nil if it can't be found
+    def find(category_id)
+      response = client.get("category", id: category_id)
+
+      if response.success?
+        Category.new(response.body, client: client)
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/ecwid_api/client.rb

@@ -1,4 +1,5 @@
 require 'faraday'
+require 'faraday_middleware'
 
 module EcwidApi
   # Public: Client objects manage the connection and interface to a single Ecwid
@@ -69,6 +70,11 @@ module EcwidApi
       connection.get(path, params)
     end
 
+    # Public: Returns the Category API
+    def categories
+      @categories ||= CategoryApi.new(self)
+    end
+
     private
 
     # Private: Resets the connection.
@@ -80,7 +86,10 @@ module EcwidApi
 
     # Private: Returns a Faraday connection to interface with the Ecwid API
     def connection
-      @connection ||= Faraday.new(url: store_url)
+      @connection ||= Faraday.new store_url do |conn|
+        conn.response :json, content_type: /\bjson$/
+        conn.adapter  Faraday.default_adapter
+      end
     end
   end
 end

data/lib/ecwid_api/entity.rb

@@ -0,0 +1,67 @@
+module EcwidApi
+  class Entity
+    # Private: Gets the Client
+    attr_reader :client
+    private :client
+
+    # Private: Gets the Hash of data
+    attr_reader :data
+    private :data
+
+    # Public: Initialize a new entity with a reference to the client and data
+    #
+    # data   - A Hash of data that represents the properties of this Entity
+    # opts   - A Hash of options
+    #          :client - The EcwidApi::Client creating the Entity
+    #
+    def initialize(data, opts={})
+      @client, @data = opts[:client], data
+    end
+
+    # Public: Returns a property of the data (actual property name)
+    #
+    # key - A Symbol or String of the property. The key should be the actual
+    #       key according to the Ecwid API documentation for the given entity.
+    #       Typically, this is camel cased.
+    #
+    # Examples
+    #
+    #   entity[:parentId]
+    #   entity["parentId"]
+    #
+    # Returns the value of the property, or nil if it doesn't exist
+    def [](key)
+      data[key.to_s]
+    end
+
+    # Public: Get a property of the data (snake_case)
+    #
+    # This is used as a helper to allow easy access to the data. It will work
+    # with both CamelCased and snake_case keys. For example, if the data
+    # contains a "parentId" key, then calling `entity.parent_id` should work.
+    #
+    # This will NOT return null of the property doesn't exist on the data!
+    #
+    # Examples
+    #
+    #   entity.parent_id    # same as `entity["parentId"]`
+    #
+    # TODO: #method_missing isn't the ideal solution because Ecwid will only
+    # return a property if it doesn't have a null value. An example of this are
+    # the top level categories. They don't have a parentId, so that property
+    # is ommitted from the API response. Calling `category.parent_id` will
+    # result in an "undefined method `parent_id'". However, calling `#parent_id`
+    # on any other category will work.
+    #
+    # Returns the value of the property
+    def method_missing(method, *args)
+      method_string = method.to_s
+
+      [ method_string, method_string.camel_case ].each do |key|
+        return data[key] if data.has_key?(key)
+      end
+
+      super method, *args
+    end
+  end
+end

data/lib/ecwid_api/version.rb

@@ -1,3 +1,3 @@
 module EcwidApi
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/ext/string.rb

@@ -0,0 +1,5 @@
+class String
+  def camel_case
+    split('_').inject([]){ |buffer,e| buffer.push(buffer.empty? ? e : e.capitalize) }.join
+  end
+end

data/spec/category_api_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+describe EcwidApi::CategoryApi, faraday: true do
+  let(:client) { EcwidApi::Client.new { |config| config.store_id = '12345' } }
+  subject { EcwidApi::CategoryApi.new(client) }
+
+  before(:each) do
+    faraday_client(client)
+  end
+
+  describe "#all" do
+    it "gets all of the categories from the client" do
+      expect(client).to receive(:get).with("categories", {}).and_call_original
+      subject.all
+    end
+
+    it "gets sub categories" do
+      expect(client).to receive(:get).with("categories", parent: 5).and_call_original
+      subject.all(5)
+    end
+  end
+
+  describe "#root" do
+    it "gets the root level categories" do
+      expect(subject).to receive(:all).with(0).and_call_original
+      subject.root
+    end
+  end
+
+  describe "#find" do
+    it "finds a single category" do
+      expect(client).to receive(:get).with("category", id: 5).and_call_original
+      subject.find(5)
+    end
+  end
+end

data/spec/category_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+describe EcwidApi::Category, faraday: true do
+  let(:client) { EcwidApi::Client.new { |config| config.store_id = '12345' } }
+  subject { EcwidApi::Category.new({"id" => 123, "parentId" => 456}, client: client) }
+
+  before(:each) do
+    faraday_client(client)
+  end
+
+  describe "#sub_categories" do
+    it "sends the request to the CategoryApi" do
+      expect(client.categories).to receive(:all).with(123)
+      subject.sub_categories
+    end
+
+    it "is memoized" do
+      subject.sub_categories
+      expect(client.categories).to_not receive(:all)
+      subject.sub_categories
+    end
+  end
+
+  describe "#parent" do
+    it "sends the request for the parent to the CategoryApi" do
+      expect(client.categories).to receive(:find).with(456)
+      subject.parent
+    end
+
+    context "without a parent" do
+      subject { EcwidApi::Category.new({"id" => 123}) }
+
+      it "returns nil" do
+        expect(client.categories).to_not receive(:find)
+        subject.parent.should be_nil
+      end
+    end
+  end
+end

data/spec/client_spec.rb

@@ -31,21 +31,9 @@ describe EcwidApi::Client do
     its(:store_url) { "http://app.ecwid.com/api/v1/12345" }
   end
 
-  describe "#get" do
-    let(:faraday_stubs) do
-      Faraday::Adapter::Test::Stubs.new do |stub|
-        stub.get('categories') { [200, {}, '[]'] }
-      end
-    end
-
-    let(:faraday) do
-      Faraday::new do |builder|
-        builder.adapter :test, faraday_stubs
-      end
-    end
-
+  describe "#get", faraday: true do
     before(:each) do
-      allow(subject).to receive(:connection).and_return(faraday)
+      faraday_client(subject)
     end
 
     it "delegates to the Faraday connection" do

data/spec/entity_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+describe EcwidApi::Entity do
+  let(:data) { {"id" => 123, "parentId" => 456} }
+
+  subject { EcwidApi::Entity.new(data) }
+
+  describe "#[]" do
+    it "gets data with a symbol key" do
+      subject[:id].should == 123
+    end
+
+    it "gets data with a string key" do
+      subject["parentId"].should == 456
+    end
+  end
+
+  describe "#method_missing" do
+    it "gets data with snake_cased messages" do
+      subject.parent_id.should == 456
+    end
+  end
+end

data/spec/fixtures/categories.json

@@ -0,0 +1,22 @@
+[
+  {
+    "id": 9389012,
+    "name": "Bariatric Products",
+    "url": "http://www.example.com#!/~/category/id=9389012",
+    "productCount": 98
+  },
+  {
+    "id": 9389013,
+    "parentId": 9389012,
+    "name": "Aids for Daily Living",
+    "url": "http://www.example.com#!/~/category/id=9389013",
+    "productCount": 72
+  },
+  {
+    "id": 9389106,
+    "parentId": 9389012,
+    "name": "Mobility",
+    "url": "http://www.example.com#!/~/category/id=9389106",
+    "productCount": 12
+  }
+]

data/spec/fixtures/category.json

@@ -0,0 +1,7 @@
+{
+  "id": 9389013,
+  "parentId": 9389012,
+  "name": "Aids for Daily Living",
+  "url": "http://www.example.com#!/~/category/id=9389013",
+  "productCount": 72
+}

data/spec/helpers/faraday.rb

@@ -0,0 +1,30 @@
+require 'faraday'
+
+module Helpers
+  module Faraday
+    def fixtures
+      %w(categories category)
+    end
+
+    def faraday_stubs
+      ::Faraday::Adapter::Test::Stubs.new do |stub|
+        fixtures.each do |fixture|
+          stub.get(fixture) { [ 200, {"Content-Type" => "application/json"}, File.read("spec/fixtures/#{fixture}.json") ] }
+        end
+      end
+    end
+
+    # Public: Returns a test Faraday::Connection
+    def faraday
+      ::Faraday.new do |builder|
+        builder.response :json, content_type: /\bjson$/
+        builder.adapter :test, faraday_stubs
+      end
+    end
+
+    # Public: Uses the Faraday stub connection with the client
+    def faraday_client(client)
+      allow(client).to receive(:connection).and_return(faraday)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -6,12 +6,15 @@
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
 
 require "ecwid_api"
+require "helpers/faraday"
 
 RSpec.configure do |config|
   config.treat_symbols_as_metadata_keys_with_true_values = true
   config.run_all_when_everything_filtered = true
   config.filter_run :focus
 
+  config.include Helpers::Faraday, faraday: true
+
   # Run specs in random order to surface order dependencies. If you find an
   # order dependency and want to debug it, you can fix the order by providing
   # the seed, which is printed after each run.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecwid_api
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - David Biehl
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-06 00:00:00.000000000 Z
+date: 2014-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,20 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 0.9.0
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.1
 description: 
 email:
 - me@davidbiehl.com
@@ -81,11 +95,21 @@ files:
 - Rakefile
 - ecwid_api.gemspec
 - lib/ecwid_api.rb
+- lib/ecwid_api/category.rb
+- lib/ecwid_api/category_api.rb
 - lib/ecwid_api/client.rb
+- lib/ecwid_api/entity.rb
 - lib/ecwid_api/error.rb
 - lib/ecwid_api/version.rb
+- lib/ext/string.rb
+- spec/category_api_spec.rb
+- spec/category_spec.rb
 - spec/client_spec.rb
 - spec/ecwid_api_spec.rb
+- spec/entity_spec.rb
+- spec/fixtures/categories.json
+- spec/fixtures/category.json
+- spec/helpers/faraday.rb
 - spec/spec_helper.rb
 homepage: ''
 licenses:
@@ -112,6 +136,12 @@ signing_key:
 specification_version: 4
 summary: A client for the Ecwid REST API
 test_files:
+- spec/category_api_spec.rb
+- spec/category_spec.rb
 - spec/client_spec.rb
 - spec/ecwid_api_spec.rb
+- spec/entity_spec.rb
+- spec/fixtures/categories.json
+- spec/fixtures/category.json
+- spec/helpers/faraday.rb
 - spec/spec_helper.rb