ecwid_api 0.0.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 67727922f8d2fc5ab19839abda31f4ae709b67e8
-  data.tar.gz: 8e78ebe2a0dc6e83da2a9235e08a57704a04b9c4
+SHA256:
+  metadata.gz: b3586666f15cbba13b4138fd19fba02ac3e1dffccc70803d975215e447b8471b
+  data.tar.gz: 9aadcd7b9217e1e92cebdaba858da43cf359873b7d2be100a63f514313da63fd
 SHA512:
-  metadata.gz: f8e57e93e2c5fc0e4109955f3a1aefe311e5cf9edd868a8fb0a5feb1bca59e06eb81d07161b2f53af4c426b9eff96eacc9a4bee59adfb79c7bd4db3b82bbbe9b
-  data.tar.gz: 5065b8ba1deff18ee542f71c68ec6b478859e19fc1ca079a419cd46dac3295c6df934c9befc467d80b46fa178b6cbbb327bf82cd7a5f309e8d060a364b521509
+  metadata.gz: 0d83a8bf4a7460bdbbf86b878b3383bd29fbb40659a7b3f3e796b058d20e36d6ec4ff8a0af33f50e34d888157eb3d75d28aec4d8a2c9b92870e19928fd0e504c
+  data.tar.gz: ce28316fc8cee04433d47b04ea9c58d79c6b2519aab5cd27735338268601c763c9d4cde6cef4afe463169078d94611febb637f93d0dd77f0861420df34a05159

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/README.md

@@ -2,7 +2,20 @@
 
 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)
+[![Code Climate](https://codeclimate.com/github/vishalzambre/ecwid_api.png)](https://codeclimate.com/github/vishalzambre/ecwid_api)
+[![Build Status](https://travis-ci.org/vishalzambre/ecwid_api.svg?branch=master)](https://travis-ci.org/vishalzambre/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/vishalzambre/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
 
@@ -20,44 +33,56 @@ Or install it yourself as:
 
 ## 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`.
+### Get Authorized with OAuth2
 
-    require 'ecwid_api'
+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:
 
-    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'
+    @auth = EcwidApi::OAuth.new do |config|
+      config.client_id = "the client id"
+      config.client_secret = "the client secret (shh...)"
+      config.redirect_uri   = "https://example.com/oauth"
+      config.scope         = "the_permissions_i_want"
     end
 
-## APIs
+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:
 
-### Category API
+    link_to @auth.oauth_url, "Click here to Authorize this Groovy App!"
 
-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.
+When the user authorizes your app, they will be redirected to the `redirect_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`.
 
-    api = client.categories
-    # => #<EcwidApi::CategoryApi>
+    # https://example.com/oauth?code=super_secret_temporary_code
 
-    api.all
-    # Returns an Array of all of the `EcwidApi::Category` objects
+    token = @auth.access_token(params[:code])
 
-    api.root
-    # Returns an Array of the top-level `EcwidApi::Category` objects for the
-    # store
+    token.access_token  # the token for the Client
+    token.store_id      # the store_id for the Client
 
-    api.find(123)
-    # Returns the `EcwidApi::Category` with an ID of 123
+### 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
 
-#### EcwidApi::Category Objects
+### Entities
 
-The properties of an `EcwidApi::Category` object can be accessed using the `[]`
-method, or with special snake_cased helper methods.
+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
@@ -76,7 +101,27 @@ method, or with special snake_cased helper methods.
     cat.parent_id     # Access with a snake_case method
     # => 456
 
-Each `EcwidApi::Category` also has methods to find any sub-categories, and the
+### 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
@@ -85,13 +130,52 @@ parent category, if there is one.
     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({createdFrom: "1982-05-17"})
+    # Paremters can be passed as a Hash.
+    # See http://api.ecwid.com/#search-orders
+    # 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/v1/[STORE-ID]/categories?parent=1
+    # GET https://app.ecwid.com/api/v3/[STORE-ID]/categories?parent=1
 
     client.get("categories", parent: 1)
 
@@ -104,7 +188,7 @@ JSON.
 
 ### Ecwid API Documentation
 
-The [Ecwid API documentation](http://kb.ecwid.com/w/page/25232810/API)
+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
@@ -112,12 +196,20 @@ that feature.
 
 ## Contributing
 
-1. Fork it ( http://github.com/davidbiehl/ecwid_api/fork )
+1. Fork it ( http://github.com/vishalzambre/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
 
+## Authors
+
+* **Vishal Zambre** - *Current work* - [vishalzambre](https://github.com/vishalzambre)
+* **David Biehl** - *Initial work* - [davidbiehl](https://github.com/davidbiehl)
+
+See also the list of [contributors](https://github.com/vishalzambre/ecwid_api/contributors) who participated in this project.
+
+
 ## License
 
 The MIT License (MIT)

data/ecwid_api.gemspec

@@ -6,21 +6,23 @@ require 'ecwid_api/version'
 Gem::Specification.new do |spec|
   spec.name          = "ecwid_api"
   spec.version       = EcwidApi::VERSION
-  spec.authors       = ["David Biehl"]
-  spec.email         = ["me@davidbiehl.com"]
+  spec.authors       = ["David Biehl", "Vishal Zambre"]
+  spec.email         = ["v.zambre@gmail.com"]
   spec.summary       = %q{A client for the Ecwid REST API}
-  spec.homepage      = ""
+  spec.description   = %q{A client for the Ecwid REST API in Ruby}
+  spec.homepage      = "https://github.com/vishalzambre/ecwid_api"
   spec.license       = "MIT"
+  spec.post_install_message = "Thanks for installing!"
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.5"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec", "~> 2.14.1"
+  spec.add_development_dependency "bundler", "~> 1.5", ">= 1.5"
+  spec.add_development_dependency "rake", "~> 0"
+  spec.add_development_dependency "rspec", "~> 3.5", ">= 3.5"
 
-  spec.add_dependency "faraday", "~> 0.9.0"
-  spec.add_dependency "faraday_middleware", "~> 0.9.1"
+  spec.add_dependency "faraday", "~> 0.9"
+  spec.add_dependency "faraday_middleware", "~> 0.9"
 end

data/lib/ecwid_api.rb

@@ -1,39 +1,28 @@
 require "ecwid_api/version"
 require "ext/string"
+require 'faraday'
+require 'faraday_middleware'
+
+require_relative "ecwid_api/error"
 
 # Public: This is the main namespace for the EcwidApi. It can be used to store
 # the default client.
 #
 module EcwidApi
-  autoload :Client, "ecwid_api/client"
-  autoload :Error, "ecwid_api/error"
-  autoload :Entity, "ecwid_api/entity"
+  require_relative "ecwid_api/o_auth"
+  require_relative "ecwid_api/client"
+  require_relative "ecwid_api/error"
+  require_relative "ecwid_api/api"
+  require_relative "ecwid_api/entity"
 
-  autoload :CategoryApi, "ecwid_api/category_api"
-  autoload :Category, "ecwid_api/category"
+  require_relative "ecwid_api/category"
+  require_relative "ecwid_api/customer"
+  require_relative "ecwid_api/order"
+  require_relative "ecwid_api/order_item"
+  require_relative "ecwid_api/person"
+  require_relative "ecwid_api/product_combination"
 
-  class << self
-    # Public: Gets and configures a default client
-    #
-    # To configure the default client, just pass a block.
-    #
-    # Examples
-    #
-    #   EcwidApi.default_client do |config|
-    #     config.store_id = '12345'
-    #     config.order_secret_key = 'ORDER_SECRET_KEY'
-    #     config.product_secret_key = 'PRODUCT_SECRET_KEY'
-    #   end
-    #
-    #   client = EcwidApi.default_client.store_id
-    #   # => "12345"
-    #
-    # Returns an EcwidApi::Client, or null if one hasn't been configured
-    def default_client(&block)
-      if block_given?
-        @default_client = Client.new(&block)
-      end
-      @default_client
-    end
-  end
+  require_relative "ecwid_api/product"
+  require_relative "ecwid_api/product_type"
+  require_relative "ecwid_api/product_type_attribute"
 end

data/lib/ecwid_api/api.rb

@@ -0,0 +1,12 @@
+module EcwidApi
+  module Api
+    require_relative "api/base"
+
+    require_relative "api/categories"
+    require_relative "api/customers"
+    require_relative "api/orders"
+    require_relative "api/product_combinations"
+    require_relative "api/product_types"
+    require_relative "api/products"
+  end
+end

data/lib/ecwid_api/api/base.rb

@@ -0,0 +1,18 @@
+module EcwidApi
+  module Api
+    # Internal: A base class for common API functionality
+    class Base
+      attr_reader :client
+      private     :client
+
+      # 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,56 @@
+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)
+        find(response.body["id"])
+      end
+    end
+  end
+end

data/lib/ecwid_api/api/customers.rb

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