ecwid_api 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 67727922f8d2fc5ab19839abda31f4ae709b67e8
-  data.tar.gz: 8e78ebe2a0dc6e83da2a9235e08a57704a04b9c4
+  metadata.gz: 115d13f16d0747c45335873d314215544f80bd4c
+  data.tar.gz: c5e1874c0963ec608800587e42a9a19d2d648949
 SHA512:
-  metadata.gz: f8e57e93e2c5fc0e4109955f3a1aefe311e5cf9edd868a8fb0a5feb1bca59e06eb81d07161b2f53af4c426b9eff96eacc9a4bee59adfb79c7bd4db3b82bbbe9b
-  data.tar.gz: 5065b8ba1deff18ee542f71c68ec6b478859e19fc1ca079a419cd46dac3295c6df934c9befc467d80b46fa178b6cbbb327bf82cd7a5f309e8d060a364b521509
+  metadata.gz: 3d057bae684a112491485aa7338c54680ed9b961a069b4f28d7ca58d325219218e8ca0c13eb971b73565a5eb803913186ef430e4ef26712bd73d9a74fb25e723
+  data.tar.gz: e769e8ca8535b17e3f15b1df4ce239a01d2c7fc2acc8b193d177f98910c7f6d6d21ba0a0bc06e65a88e36b7845a1e9ac4f9daea613a56d34c1123c08a1bf3de4

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+
+rvm:
+  - "2.1.0"
+  - "2.0.0"
+  - "1.9.3"
+
+script: bundle exec rspec spec

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in ecwid_api.gemspec
 gemspec
+
+# gem "faraday", git: "https://github.com/davidbiehl/faraday.git", branch: "preserve_raw"

data/README.md

@@ -1,144 +1,228 @@
-# EcwidApi
-
-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:
-
-    gem 'ecwid_api'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install ecwid_api
-
-## Usage
-
-### Configure an new Client
-
-A `Client` will interface with a single Ecwid store. The `store_id` will need
-to be configured for each new `Client`.
-
-    require 'ecwid_api'
-
-    client = EcwidApi::Client.new do |config|
-      config.store_id           = '12345'                        # your Ecwid Store ID
-      config.url                = 'https://app.ecwid.com/api/v1' # default
-      config.order_secret_key   = 'ORDER_SECRET_KEY'
-      config.product_secret_key = 'PRODUCT_SECRET_KEY'
-    end
-
-## 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
-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
-
-    client.get("categories", parent: 1)
-
-    # => #<Faraday::Response>
-
-The `Client` is responsible for making raw requests, which is why it returns
-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. 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
-
-1. Fork it ( http://github.com/davidbiehl/ecwid_api/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
-## License
-
-The MIT License (MIT)
-
-Copyright (c) 2014 David Biehl
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-
+# EcwidApi
+
+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)
+[![Build Status](https://travis-ci.org/davidbiehl/ecwid_api.svg?branch=master)](https://travis-ci.org/davidbiehl/ecwid_api)
+
+## API v3 Warning!
+
+This is for the latest version of the API, also known as v3, which is currently
+in closed beta! The (incomplete) v1 API is still available on the
+[api-v1 branch](https://github.com/davidbiehl/ecwid_api/tree/api-v1).
+
+To participate in the beta, please contact Ecwid and they will give you the
+information necessary to configure and authorize your application with OAuth2.
+
+[Ecwid's API Documentation](http://api.ecwid.com) will be an important reference
+in order to understand what their API is capable of.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'ecwid_api'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ecwid_api
+
+## Usage
+
+### Get Authorized with OAuth2
+
+Ecwid API v3 uses OAuth2 to authorize 3rd party apps to use the API with a
+store. The `EcwidApi::OAuth` class helps facilitate this process. Once you
+get setup with a `client_id` and `client_secret` from Ecwid, configure a new
+instance like so:
+
+    @auth = EcwidApi::OAuth.new do |config|
+      config.client_id = "the client id"
+      config.client_secret = "the client secret (shh...)"
+      config.request_uri   = "https://example.com/oauth"
+      config.scope         = "the_permissions_i_want"
+    end
+
+The `#oauth_url` method will provide the URL that the user needs to go to
+to authorize your application with their store. It can be used in Rails like so:
+
+    link_to @auth.oauth_url, "Click here to Authorize this Groovy App!"
+
+When the user authorizes your app, they will be redirected to the `request_uri`
+with a `code` parameter in the query string.
+Just send that code to the `#access_token` method to complete the authorization
+and get your `access_token` and `store_id`.
+
+    # https://example.com/oauth?code=super_secret_temporary_code
+
+    token = @auth.access_token(params[:code])
+
+    token.access_token  # the token for the Client
+    token.store_id      # the store_id for the Client
+
+### Configure an new Client
+
+A `Client` will interface with a single Ecwid store. The `store_id` and OAuth
+`access_token` will need to be provided to the client.
+
+    require 'ecwid_api'
+
+    client = EcwidApi::Client.new(store_id, access_token)
+
+## The APIs
+
+### Entities
+
+Instead of returning raw JSON from the API, there are Entities that will help
+you work with the data. The [Ecwid API](http://api.ecwid.com)
+will give you all of the fields that are available for every entity. Our
+Entities will give you access to the data with the `[]` method, or a snake_case
+version of the property name. For example, with an `EcwidApi::Category` the
+following would be possible:
+
+    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
+
+### 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::Api::Categories>
+
+    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 Entities
+
+Each `EcwidApi::Category` has methods to find 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`
+
+### Order API
+
+The Order API will allow you to access the orders that have been placed in an
+Ecwid store. An instance of the Order API is available to the client
+
+    api = client.orders
+
+    api.all
+    # Returns a `PagedEnumerator` containing all of the orders for the store
+
+    api.all({date: "1982-05-17"})
+    # Paremters can be passed as a Hash.
+    # See http://kb.ecwid.com/w/page/43697230/Order%20API#Parameters for
+    # a list of available parameters
+
+    api.find(123)
+    # Returns an `EcwidApi::Order` object for order 123
+
+#### EcwidApi::Order Entities
+
+There are a few helper methods on the `EcwidApi::Order` that assist in accessing
+related Entities.
+
+    order.billing_person
+    # Returns a EcwidApi::Person
+
+    order.shipping_person
+    # Returns an EcwidApi::Person
+
+    order.items
+    # Returns an Array of EcwidApi::OrderItem objects
+
+The fulfillment status and shipping tracking code can also be updated for an
+`EcwidApi::Order` object.
+
+    order.fulfillment_status = :processing
+    order.shipping_tracking_code = "1Z1234567890"
+    order.save
+
+### Making Ad-Hoc Requests with the Client
+
+To make a request, simply call the `#get` method on the client passing in the
+relative path and any parameters it requires.
+For example, to get some categories:
+
+    # GET https://app.ecwid.com/api/v3/[STORE-ID]/categories?parent=1
+
+    client.get("categories", parent: 1)
+
+    # => #<Faraday::Response>
+
+The `Client` is responsible for making raw requests, which is why it returns
+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://api.ecwid.com)
+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
+
+1. Fork it ( http://github.com/davidbiehl/ecwid_api/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+The MIT License (MIT)
+
+Copyright (c) 2014 David Biehl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/ecwid_api.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.5"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~> 2.14.1"
+  spec.add_development_dependency "pry"
 
   spec.add_dependency "faraday", "~> 0.9.0"
   spec.add_dependency "faraday_middleware", "~> 0.9.1"

data/lib/ecwid_api/api/base.rb

@@ -0,0 +1,17 @@
+module EcwidApi
+  module Api
+    # Internal: A base class for common API functionality
+    class Base
+      include Api
+
+      # Public: Initializes a new EcwidApi::CategoryApi
+      #
+      # client - The EcwidApi::Client to use with the API
+      #
+      def initialize(client)
+        @client = client
+        raise Error.new("The client cannot be nil") unless client
+      end
+    end
+  end
+end

data/lib/ecwid_api/api/categories.rb

@@ -0,0 +1,57 @@
+require_relative "../paged_ecwid_response"
+
+module EcwidApi
+  module Api
+    class Categories < Base
+      # 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(params = {})
+        PagedEcwidResponse.new(client, "categories", params) do |category_hash|
+          Category.new(category_hash, client: client)
+        end.sort_by(&:order_by)
+      end
+
+      # Public: Returns an Array of the root level EcwidApi::Category objects
+      def root(params = {})
+        all(params.merge(parent: 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(id)
+        response = client.get("categories/#{id}")
+
+        if response.success?
+          Category.new(response.body, client: client)
+        else
+          nil
+        end
+      rescue Zlib::BufError
+        nil
+      end
+
+      # Public: Creates a new Category
+      #
+      # params - a Hash of API keys and their corresponding values
+      #
+      # Returns a new Category entity
+      def create(params)
+        response = client.post("categories", params)
+
+        raise_on_failure(response) { |response| find(response.body["id"]) }
+      end
+    end
+  end
+end

data/lib/ecwid_api/api/orders.rb

@@ -0,0 +1,36 @@
+require_relative "../paged_ecwid_response"
+
+module EcwidApi
+  module Api
+    # Public: This is the Ecwid API for Orders. It abstracts the end-points
+    # of the Ecwid API that deal with orders.
+    class Orders < Base
+      # Public: Gets Orders from the Ecwid API
+      #
+      # params - optional parameters that can be used to filter the request.
+      #          For a list of params, please refer to the API documentation:
+      #          http://kb.ecwid.com/w/page/43697230/Order%20API
+      #          Note that the limit and offset parameters will be overridden
+      #          since all orders will be returned and enumerated
+      #
+      # Returns a PagedEnumerator of `EcwidApi::Order` objects
+      def all(params = {})
+        PagedEcwidResponse.new(client, "orders", params) do |order_hash|
+          Order.new(order_hash, client: client)
+        end
+      end
+
+      # Public: Finds a an Order given an Ecwid order_number
+      #
+      # order_number - an Integer that is the Ecwid Order number
+      #
+      # Returns an EcwidApi::Order if found, nil if not
+      def find(order_number)
+        response = client.get("orders/#{order_number}")
+        if response.success?
+          Order.new(response.body, client: client)
+        end
+      end
+    end
+  end
+end

data/lib/ecwid_api/api/product_combinations.rb

@@ -0,0 +1,51 @@
+module EcwidApi
+  module Api
+    class ProductCombinations < Base
+      include Api
+      include Enumerable
+
+      attr_reader :product
+
+      def initialize(product, client)
+        @product = product
+        super(client)
+      end
+
+      def all
+        response = client.get("products/#{product.id}/combinations")
+
+        if response.success?
+          response.body.map do |data|
+            ProductCombination.new(data, client: client, product: product)
+          end
+        end
+      end
+
+      def each(&block)
+        all = self.all || []
+
+        all.each(&block)
+      end
+
+      def find(id)
+        response = client.get("products/#{product.id}/combinations/#{id}")
+
+        if response.success?
+          ProductCombination.new(response.body, product: product, client: client)
+        end
+      end
+
+      def create(params)
+        response = client.post("products/#{product.id}/combinations", params)
+
+        raise_on_failure(response) { find(response.body["id"]) }
+      end
+
+      def delete_all!
+        client.delete("products/#{product.id}/combinations").tap do |response|
+          raise_on_failure(response)
+        end
+      end
+    end
+  end
+end

data/lib/ecwid_api/api/products.rb

@@ -0,0 +1,64 @@
+require_relative "../paged_ecwid_response"
+
+module EcwidApi
+  module Api
+    class Products < Base
+      # Public: Get all of the Product objects for the Ecwid store
+      #
+      # Returns an Array of Product objects
+      def all(params = {})
+        PagedEcwidResponse.new(client, "products", params) do |product_hash|
+          Product.new(product_hash, client: client)
+        end
+      end
+
+      # Public: Finds a single product by product ID
+      #
+      # id - an Ecwid product ID
+      #
+      # Returns a Product object, or nil if one can't be found
+      def find(id)
+        response = client.get("products/#{id}")
+        if response.success?
+          Product.new(response.body, client: client)
+        end
+      end
+
+      # Public: Finds a single Product by SKU
+      #
+      # sku - a SKU of a product
+      #
+      # Returns a Product object, or nil if one can't be found
+      def find_by_sku(sku)
+        all(keyword: sku).find { |product| product[:sku] == sku }
+      end
+
+      # Public: Creates a new Product
+      #
+      # params - a Hash
+      #
+      # Raises an Error if there is a problem
+      #
+      # Returns a Product object
+      def create(params)
+        response = client.post("products", params)
+
+        raise_on_failure(response) {|response| find(response.body["id"]) }
+      end
+
+      # Public: Updates an existing Product
+      #
+      # id - the Ecwid product ID
+      # params - a Hash
+      #
+      # Raises an Error if there is a problem
+      #
+      # Returns a Product object
+      def update(id, params)
+        response = client.put("products/#{id}", params)
+
+        raise_on_failure(response) { find(id) }
+      end
+    end
+  end
+end