ecwid_api 0.0.2 → 0.1.0

data/lib/ecwid_api/api.rb

@@ -0,0 +1,31 @@
+module EcwidApi
+  # Internal: A base class for common API functionality
+  module Api
+    autoload :Base,                "ecwid_api/api/base"
+    autoload :Orders,              "ecwid_api/api/orders"
+    autoload :Products,            "ecwid_api/api/products"
+    autoload :Categories,          "ecwid_api/api/categories"
+    autoload :ProductCombinations, "ecwid_api/api/product_combinations"
+
+    # Private: Gets the Client
+    attr_reader :client
+    private     :client
+
+    # Private: Raises an Error if a request failed, otherwise it will
+    # yield the block
+    #
+    # response - a Faraday::Response object
+    #
+    # Yield if the response was successful
+    #
+    # Raises an error with the status code and reason if the response failed
+    #
+    def raise_on_failure(response)
+      if response.success?
+        yield(response) if block_given?
+      else
+        raise ResponseError.new(response)
+      end
+    end
+  end
+end

data/lib/ecwid_api/category.rb

@@ -1,14 +1,69 @@
+require "open-uri"
+
 module EcwidApi
   class Category < Entity
+    self.url_root = "categories"
+
+    ecwid_reader :id, :parentId, :orderBy, :thumbnailUrl, :originalImageUrl,
+                 :name, :url, :productCount, :description, :enabled, :productIds
+
+    ecwid_writer :name, :parentId, :orderBy, :description, :enabled, :productIds
+
     # Public: Returns an Array of sub categories for the Category
-    def sub_categories
-      @sub_categories ||= client.categories.all(id)
+    def sub_categories(params = {})
+      @sub_categories ||= client.categories.all(params.merge(parent: id))
+    end
+
+    # Public: Returns an Array of all of the sub categories (deep) for the
+    #         Category
+    def all_sub_categories(params = {})
+      @all_sub_categories ||= sub_categories(params) + sub_categories.flat_map do |sub|
+        sub.all_sub_categories(params)
+      end
     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
+      @parent ||= begin
+        parent_id = data["parentId"]
+        client.categories.find(parent_id) if parent_id
+      end
+    end
+
+    def parents
+      if parent
+        parent.parents + [parent]
+      else
+        []
+      end
+    end
+
+    # Public: Returns the Products that belong to the Category
+    #
+    # params - a Hash of values that can be used for a Prdocut search
+    #
+    # Returns an Enumeration of Products
+    def products(params = {})
+      @products ||= product_ids.map do |product_id|
+        client.products.find(product_id)
+      end
+    end
+
+    def product_ids
+      super || []
+    end
+
+    # Public: Uploads an image for the Category
+    #
+    # filename - a String that is the path to a local file or a URL
+    #
+    # Returns a Faraday::Response object
+    def upload_image!(filename)
+      client.post("categories/#{id}/image") do |req|
+        req.body = open(filename).read
+      end.tap do |response|
+        raise_on_failure(response)
+      end
     end
   end
 end

data/lib/ecwid_api/client.rb

@@ -1,95 +1,66 @@
-require 'faraday'
-require 'faraday_middleware'
-
-module EcwidApi
-  # Public: Client objects manage the connection and interface to a single Ecwid
-  # store.
-  #
-  # Examples
-  #
-  #   client = EcwidApi::Client.new do |config|
-  #     config.store_id = '12345'
-  #     config.url = 'http://app.ecwid.com/api/v1'
-  #     config.order_secret_key = 'ORDER_SECRET_KEY'
-  #     config.product_secret_key = 'PRODUCT_SECRET_KEY'
-  #   end
-  #
-  class Client
-    # The default base URL for the Ecwid API
-    DEFAULT_URL = "https://app.ecwid.com/api/v1"
-
-    # Public: Returns the Ecwid Store ID
-    attr_reader :store_id
-
-    # Public: Gets or sets the Order API Secret Key for the Ecwid Store
-    attr_accessor :order_secret_key
-
-    # Public: Gets or sets the default Product API Secret Key for the Ecwid Store
-    attr_accessor :product_secret_key
-
-    def initialize
-      yield(self) if block_given?
-      raise Error.new("The store_id is required") unless store_id
-    end
-
-    # Public: Returns the base URL of the Ecwid API
-    def url
-      @url || DEFAULT_URL
-    end
-
-    # Public: Sets the base URL for the Ecwid API
-    def url=(url)
-      reset_connection
-      @url = url
-    end
-
-    # Public: Sets the Ecwid Store ID
-    def store_id=(store_id)
-      reset_connection
-      @store_id = store_id
-    end
-
-    # Public: The URL of the API for the Ecwid Store
-    def store_url
-      "#{url}/#{store_id}"
-    end
-
-    # Public: Sends a GET request to the Ecwid API
-    #
-    # path   - The String path for the URL of the request without the base URL
-    # params - A Hash of query string parameters
-    #
-    # Examples
-    #
-    #   # Gets the Categories where the parent Category is 1
-    #   client.get("categories", parent: 1)
-    #   # => #<Faraday::Response>
-    #
-    # Returns a Faraday::Response
-    def get(path, params={})
-      connection.get(path, params)
-    end
-
-    # Public: Returns the Category API
-    def categories
-      @categories ||= CategoryApi.new(self)
-    end
-
-    private
-
-    # Private: Resets the connection.
-    #
-    # Should be used if the base URL to the Ecwid API changes
-    def reset_connection
-      @connection = nil
-    end
-
-    # Private: Returns a Faraday connection to interface with the Ecwid API
-    def connection
-      @connection ||= Faraday.new store_url do |conn|
-        conn.response :json, content_type: /\bjson$/
-        conn.adapter  Faraday.default_adapter
-      end
-    end
-  end
+module EcwidApi
+  # Public: Client objects manage the connection and interface to a single Ecwid
+  # store.
+  #
+  # Examples
+  #
+  #   client = EcwidApi::Client.new(store_id: '12345', token: 'the access_token')
+  #   client.get "/products"
+  #
+  class Client
+    extend Forwardable
+
+    # The default base URL for the Ecwid API
+    DEFAULT_URL = "https://app.ecwid.com/api/v3"
+
+    # Public: Returns the Ecwid Store ID
+    attr_reader :store_id
+    attr_reader :token
+    attr_reader :adapter
+
+    # Public: Initializes a new Client to interact with the API
+    #
+    # store_id - the Ecwid store_id to interact with
+    # token    - the authorization token provided by oAuth. See the
+    #            Authentication class
+    #
+    def initialize(store_id, token, adapter = Faraday.default_adapter)
+      @store_id, @token, @adapter = store_id, token, adapter
+    end
+
+    # Public: The URL of the API for the Ecwid Store
+    def store_url
+      "#{DEFAULT_URL}/#{store_id}"
+    end
+
+    def_delegators :connection, :get, :post, :put, :delete
+
+    # Public: Returns the Category API
+    def categories
+      @categories ||= Api::Categories.new(self)
+    end
+
+    # Public: Returns the Order API
+    def orders
+      @orders ||= Api::Orders.new(self)
+    end
+
+    # Public: Returns the Products API
+    def products
+      @products ||= Api::Products.new(self)
+    end
+
+    # Private: Returns a Faraday connection to interface with the Ecwid API
+    def connection
+      @connection ||= Faraday.new store_url do |conn|
+        conn.request  :oauth2, token, param_name: :token
+        conn.request  :json
+
+        conn.response :json, content_type: /\bjson$/
+        conn.response :logger
+
+        conn.adapter  adapter
+      end
+    end
+  end
 end

data/lib/ecwid_api/entity.rb

@@ -1,12 +1,86 @@
 module EcwidApi
   class Entity
-    # Private: Gets the Client
-    attr_reader :client
-    private :client
+    include Api
 
     # Private: Gets the Hash of data
     attr_reader :data
-    private :data
+    protected   :data
+
+    class << self
+      attr_accessor :url_root
+
+      def define_accessor(attribute, &block)
+        if const_defined?(:Accessors, false)
+          mod = const_get(:Accessors)
+        else
+          mod = const_set(:Accessors, Module.new)
+          include mod
+        end
+
+        mod.module_eval do
+          define_method(attribute, &block)
+        end
+      end
+
+      private :define_accessor
+
+      # Public: Creates a snake_case access method from an Ecwid property name
+      #
+      # Example
+      #
+      #   class Product < Entity
+      #     ecwid_reader :id, :inStock
+      #   end
+      #
+      #   product = client.products.find(12)
+      #   product.in_stock
+      #
+      def ecwid_reader(*attrs)
+        attrs.map(&:to_s).each do |attribute|
+          method = attribute.underscore
+          define_accessor(method) do
+            self[attribute]
+          end unless method_defined?(attribute.underscore)
+        end
+      end
+
+      # Public: Creates a snake_case writer method from an Ecwid property name
+      #
+      # Example
+      #
+      #   class Product < Entity
+      #     ecwid_writer :inStock
+      #   end
+      #
+      #   product = client.products.find(12)
+      #   product.in_stock = true
+      #
+      def ecwid_writer(*attrs)
+        attrs.map(&:to_s).each do |attribute|
+          method = "#{attribute.underscore}="
+          define_accessor(method) do |value|
+            @new_data[attribute] = value
+          end unless method_defined?(method)
+        end
+      end
+
+      # Public: Creates a snake_case accessor method from an Ecwid property name
+      #
+      # Example
+      #
+      #   class Product < Entity
+      #     ecwid_accessor :inStock
+      #   end
+      #
+      #   product = client.products.find(12)
+      #   product.in_stock
+      #   product.in_stock = true
+      #
+      def ecwid_accessor(*attrs)
+        ecwid_reader(*attrs)
+        ecwid_writer(*attrs)
+      end
+    end
 
     # Public: Initialize a new entity with a reference to the client and data
     #
@@ -16,6 +90,7 @@ module EcwidApi
     #
     def initialize(data, opts={})
       @client, @data = opts[:client], data
+      @new_data = {}
     end
 
     # Public: Returns a property of the data (actual property name)
@@ -31,37 +106,74 @@ module EcwidApi
     #
     # Returns the value of the property, or nil if it doesn't exist
     def [](key)
-      data[key.to_s]
+      @new_data[key.to_s] || 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!
+    # Public: The URL of the entity
     #
-    # Examples
+    # Returns a String that is the URL of the entity
+    def url
+      url_root = self.class.url_root
+      raise Error.new("Please specify a url_root for the #{self.class.to_s}") unless url_root
+
+      if url_root.respond_to?(:call)
+        url_root = instance_exec(&url_root)
+      end
+
+      url_root + "/#{id}"
+    end
+
+    def assign_attributes(attributes)
+      attributes.each do |key, val|
+        send("#{key}=", val)
+      end
+    end
+
+    def assign_raw_attributes(attributes)
+      attributes.each do |key, val|
+        @new_data[key.to_s] = val
+      end
+    end
+
+    def update_attributes(attributes)
+      assign_attributes(attributes)
+      save
+    end
+
+    def update_raw_attributes(attributes)
+      assign_raw_attributes(attributes)
+      save
+    end
+
+    # Public: Saves the Entity
     #
-    #   entity.parent_id    # same as `entity["parentId"]`
+    # Saves anything stored in the @new_data hash
     #
-    # 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.
+    # path - the URL of the entity
     #
-    # Returns the value of the property
-    def method_missing(method, *args)
-      method_string = method.to_s
+    def save
+      unless @new_data.empty?
+        client.put(url, @new_data).tap do |response|
+          raise_on_failure(response)
+          @data.merge!(@new_data)
+          @new_data.clear
+        end
+      end
+    end
 
-      [ method_string, method_string.camel_case ].each do |key|
-        return data[key] if data.has_key?(key)
+    # Public: Destroys the Entity
+    def destroy!
+      client.delete(url).tap do |response|
+        raise_on_failure(response)
       end
+    end
+
+    def to_hash
+      data
+    end
 
-      super method, *args
+    def to_json(*args)
+      data.to_json(*args)
     end
   end
 end

data/lib/ecwid_api/error.rb

@@ -1,3 +1,13 @@
-module EcwidApi
-  class Error < StandardError; end;
+module EcwidApi
+  class Error < StandardError; end;
+
+  class ResponseError < Error
+    def initialize(response)
+      if response.respond_to?(:reason_phrase)
+        super("#{response.reason_phrase} (#{response.status})")
+      else
+        super "The Ecwid API responded with an error (#{response.status})"
+      end
+    end
+  end
 end

data/lib/ecwid_api/o_auth.rb

@@ -0,0 +1,106 @@
+require "cgi"
+require "ostruct"
+
+module EcwidApi
+  # Public: Authentication objects manage OAuth authentication with an Ecwid
+  #         store.
+  #
+  # Examples
+  #
+  #   app = EcwidApi::Authentication.new do |config|
+  #     # see initialize for configuration
+  #   end
+  #
+  #   app.oauth_url  # send the user here to authorize the app
+  #
+  #   token = app.access_token(params[:code]) # this is the code they provide
+  #                                           # to the redirect_uri
+  #   token.access_token
+  #   token.store_id      # these are what you need to access the API
+  #
+  class OAuth
+    CONFIG = %w(client_id client_secret scope redirect_uri)
+    attr_accessor *CONFIG
+
+    # Public: Initializes a new Ecwid Authentication for OAuth
+    #
+    # Examples
+    #
+    #   app = EcwidApi::Authentication.new do |config|
+    #     config.client_id     = "some client id"
+    #     config.client_secret = "some client secret"
+    #     config.scope         "this_is_what_i_want_to_do oh_and_that_too"
+    #     config.redirect_uri  = "https://example.com/oauth"
+    #   end
+    #
+    def initialize
+      yield(self) if block_given?
+      CONFIG.each do |method|
+        raise Error.new("#{method} is required to initialize a new EcwidApi::Authentication") unless send(method)
+      end
+    end
+
+    # Public: The URL for OAuth authorization.
+    #
+    # This is the URL that the user will need to go to to authorize the app
+    # with the Ecwid store.
+    #
+    def oauth_url
+      "https://my.ecwid.com/api/oauth/authorize?" + oauth_query
+    end
+
+    # Public: Obtain the access token in order to use the API
+    #
+    # code - the temporary code obtained from the authorization callback
+    #
+    # Examples
+    #
+    #   token = app.access_token(params[:code])
+    #   token.access_token  # the access token that authenticates each API request
+    #   token.store_id      # the authenticated Ecwid store_id
+    #
+    # Returns an OpenStruct which responds with the information needed to
+    # access the API for a store.
+    def access_token(code)
+      response = connection.post("/api/oauth/token",
+        client_id:     client_id,
+        client_secret: client_secret,
+        code:          code,
+        redirect_uri:  redirect_uri,
+        grant_type:    "authorization_code"
+      )
+
+      if response.success?
+        OpenStruct.new(response.body)
+      else
+        raise Error.new(response.body["error_description"])
+      end
+    end
+
+    private
+
+    # Private: The query parameters for the OAuth authorization request
+    #
+    # Returns a String of query parameters
+    def oauth_query
+      {
+        client_id:     client_id,
+        scope:         scope,
+        response_type: "code",
+        redirect_uri:  redirect_uri
+      }.map do |key, val|
+        "#{CGI.escape(key.to_s)}=#{CGI.escape(val.to_s)}"
+      end.join(?&)
+    end
+
+    # Private: Returns a connection for obtaining an access token from Ecwid
+    #
+    def connection
+      @connection ||= Faraday.new "https://my.ecwid.com" do |conn|
+        conn.request  :url_encoded
+        conn.response :json, content_type: /\bjson$/
+        conn.adapter  Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/ecwid_api/order.rb

@@ -0,0 +1,82 @@
+module EcwidApi
+  # Public: This is an Ecwid Order
+  class Order < Entity
+    self.url_root = "orders"
+
+    ecwid_reader :orderNumber, :vendorOrderNumber, :subtotal, :total, :email,
+                 :paymentMethod, :paymentModule, :tax, :ipAddress,
+                 :couponDiscount, :paymentStatus, :fulfillmentStatus,
+                 :refererUrl, :orderComments, :volumeDiscount, :customerId,
+                 :membershipBasedDiscount, :totalAndMembershipBasedDiscount,
+                 :discount, :usdTotal, :globalReferer, :createDate, :updateDate,
+                 :customerGroup, :discountCoupon, :items, :billingPerson,
+                 :shippingPerson, :shippingOption, :additionalInfo,
+                 :paymentParams, :discountInfo, :trackingNumber,
+                 :paymentMessage, :extTransactionId, :affiliateId,
+                 :creditCardStatus
+
+
+    ecwid_writer :subtotal, :total, :email, :paymentMethod, :paymentModule,
+                 :tax, :ipAddress, :couponDiscount, :paymentStatus,
+                 :fulfillmentStatus, :refererUrl, :orderComments,
+                 :volumeDiscount, :customerId, :membershipBasedDiscount,
+                 :totalAndMembershipBasedDiscount, :discount, :globalReferer,
+                 :createDate, :updateDate, :customerGroup, :discountCoupon,
+                 :items, :billingPerson, :shippingPerson, :shippingOption,
+                 :additionalInfo, :paymentParams, :discountInfo,
+                 :trackingNumber, :paymentMessage, :extTransactionId,
+                 :affiliateId, :creditCardStatus
+
+    VALID_FULFILLMENT_STATUSES = %w(
+      AWAITING_PROCESSING
+      PROCESSING
+      SHIPPED
+      DELIVERED
+      WILL_NOT_DELIVER
+      RETURNED
+    )
+
+    # Public: Gets the unique ID of the order
+    def id
+      order_number
+    end
+
+    # Public: Returns the billing person
+    def billing_person
+      return unless data["billingPerson"] || data["shippingPerson"]
+
+      @billing_person ||= if data["billingPerson"]
+        Person.new(data["billingPerson"])
+      else
+        shipping_person
+      end
+    end
+
+    # Public: Returns the shipping person
+    def shipping_person
+      return unless data["shippingPerson"] || data["billingPerson"]
+      @shipping_person ||= if data["shippingPerson"]
+        Person.new(data["shippingPerson"])
+      else
+        billing_person
+      end
+    end
+
+    # Public: Returns a Array of `OrderItem` objects
+    def items
+      @items ||= data["items"].map { |item| OrderItem.new(item) }
+    end
+
+    def fulfillment_status=(status)
+      status = status.to_s.upcase
+      unless VALID_FULFILLMENT_STATUSES.include?(status)
+        raise Error("#{status} is an invalid fullfillment status")
+      end
+      super(status)
+    end
+
+    def fulfillment_status
+      super && super.downcase.to_sym
+    end
+  end
+end

data/lib/ecwid_api/order_item.rb

@@ -0,0 +1,17 @@
+module EcwidApi
+  class OrderItem < Entity
+    ecwid_reader :id, :productId, :categoryId, :price, :productPrice, :weight,
+                 :sku, :quantity, :shortDescription, :tax, :shipping,
+                 :quantityInStock, :name, :tangible, :trackQuantity,
+                 :fixedShippingRateOnly, :imageId, :fixedShippingRate,
+                 :digital, :productAvailable, :couponApplied, :selectedOptions,
+                 :taxes, :files
+
+    # Public: Returns the default `Category` that the product belongs to
+    def category
+      client.categories.find(data["categoryId"])
+    end
+
+    # TODO: get the product
+  end
+end